From ea3c0ca53bb2626f2ef0e9b1a65c19d591788148 Mon Sep 17 00:00:00 2001 From: Keith Winstein Date: Wed, 15 Feb 2012 13:12:21 -0500 Subject: [PATCH] Add man pages (closes #7 github issue) --- ChangeLog | 6 +++ Makefile.am | 4 +- configure.ac | 4 +- debian/changelog | 8 ++++ man/Makefile.am | 1 + man/mosh-client.1 | 66 ++++++++++++++++++++++++++++ man/mosh-server.1 | 71 ++++++++++++++++++++++++++++++ man/mosh.1 | 109 ++++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 265 insertions(+), 4 deletions(-) create mode 100644 man/Makefile.am create mode 100644 man/mosh-client.1 create mode 100644 man/mosh-server.1 create mode 100644 man/mosh.1 diff --git a/ChangeLog b/ChangeLog index a378648..0da3f73 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2011-02-15 Keith Winstein + + * Version 0.94 released. + + * Make man pages + 2011-02-13 Keith Winstein * Version 0.93 released. diff --git a/Makefile.am b/Makefile.am index 8e659da..6dd9991 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,3 +1,3 @@ ACLOCAL_AMFLAGS = --install -I m4 -SUBDIRS = src scripts -EXTRA_DIST = ocb-license.html debian +SUBDIRS = src scripts man +EXTRA_DIST = ocb-license.html diff --git a/configure.ac b/configure.ac index eb8f060..6e07eae 100644 --- a/configure.ac +++ b/configure.ac @@ -2,7 +2,7 @@ # Process this file with autoconf to produce a configure script. AC_PREREQ([2.67]) -AC_INIT([mosh], [0.93], [mosh-devel@mit.edu]) +AC_INIT([mosh], [0.94], [mosh-devel@mit.edu]) AM_INIT_AUTOMAKE([-Wall -Werror]) AC_CONFIG_SRCDIR([src/frontend/mosh-client.cc]) AC_CONFIG_MACRO_DIR([m4]) @@ -42,5 +42,5 @@ AC_CHECK_FUNCS([clock_gettime gettimeofday inet_ntoa iswprint memchr memset nl_l # Checks for protobuf PKG_CHECK_MODULES([protobuf_lite], [protobuf-lite]) -AC_CONFIG_FILES([Makefile src/Makefile src/crypto/Makefile src/frontend/Makefile src/network/Makefile src/protobufs/Makefile src/statesync/Makefile src/terminal/Makefile src/util/Makefile scripts/Makefile src/examples/Makefile]) +AC_CONFIG_FILES([Makefile src/Makefile src/crypto/Makefile src/frontend/Makefile src/network/Makefile src/protobufs/Makefile src/statesync/Makefile src/terminal/Makefile src/util/Makefile scripts/Makefile src/examples/Makefile man/Makefile]) AC_OUTPUT diff --git a/debian/changelog b/debian/changelog index 6f0d3d0..6d33ced 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,11 @@ +mosh (0.94-1) unstable; urgency=low + + * Version 0.94 released. + + * Make man pages. + + -- Keith Winstein Wed, 15 Feb 2012 13:56:11 -0500 + mosh (0.93-1) unstable; urgency=low * Version 0.93 released. diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..ca7bff6 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1 @@ +dist_man_MANS = mosh.1 mosh-client.1 mosh-server.1 diff --git a/man/mosh-client.1 b/man/mosh-client.1 new file mode 100644 index 0000000..0d9ab73 --- /dev/null +++ b/man/mosh-client.1 @@ -0,0 +1,66 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH MOSH 1 "February 2012" +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.SH NAME +mosh-client \- client-side helper for mosh +.SH SYNOPSIS +MOSH_KEY=KEY +.B mosh-client +IP PORT +.br +.SH DESCRIPTION +\fBmosh-client\fP is a helper program for the +.BR mosh(1) +remote terminal application. + +\fBmosh\fP itself is a setup script that establishes an SSH +connection, runs the server-side helper \fBmosh-server\fP, +and collects the server's port number and session key. + +\fBmosh\fP then executes \fBmosh-client\fP with the server's IP +address, port, and session key. \fBmosh-client\fP runs for +the lifetime of the connection. + +The 22-byte base64 session key given by \fBmosh-server\fP is supplied +in the MOSH_KEY environment variable. This represents a 128-bit AES +key that protects the integrity and confidentiality of the session. + +For constructing new setup wrappers for remote execution facilities +other than SSH, it may be necessary to invoke \fBmosh-client\fP +directly. + +.SH SEE ALSO +.BR mosh (1), +.BR mosh-server (1). + +Project home page: +.I http://mosh.mit.edu + +.br +.SH AUTHOR +mosh was written by Keith Winstein . +.SH BUGS +\fBmosh\fP is beta software. Please report bugs to \fImosh-devel@mit.edu\fP. Users may also subscribe +to the +.nh +.I mosh-users@mit.edu +.hy +mailing list, at +.nh +.I http://mailman.mit.edu/mailman/listinfo/mosh-users +.hy +. diff --git a/man/mosh-server.1 b/man/mosh-server.1 new file mode 100644 index 0000000..a15dcf0 --- /dev/null +++ b/man/mosh-server.1 @@ -0,0 +1,71 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH MOSH 1 "February 2012" +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.SH NAME +mosh-server \- server-side helper for mosh +.SH SYNOPSIS +.B mosh-server +[IP address to bind] +.br +.SH DESCRIPTION +\fBmosh-server\fP is a helper program for the +.BR mosh(1) +remote terminal application. + +\fBmosh-server\fP binds to a high UDP port and chooses an encryption +key to protect the session. It prints both on standard output, +detaches from the terminal, and waits for the \fBmosh-client\fP to +establish a connection via UDP. + +\fBmosh-server\fP maintains an entry in the +.BR utmp(5) +file to indicate its process ID, whether the session is connected, +and the client's current IP address. + +\fBmosh-server\fP exits when the client terminates the connection. + +.SH EXAMPLE + +$ mosh-server +.br +MOSH CONNECT 41105 Olf895dcSnf7ojL4s6Qlhw +.br +[mosh-server detached, pid=16929.] +.br +$ + +.SH SEE ALSO +.BR mosh (1), +.BR mosh-client (1). + +Project home page: +.I http://mosh.mit.edu + +.br +.SH AUTHOR +mosh was written by Keith Winstein . +.SH BUGS +\fBmosh\fP is beta software. Please report bugs to \fImosh-devel@mit.edu\fP. Users may also subscribe +to the +.nh +.I mosh-users@mit.edu +.hy +mailing list, at +.nh +.I http://mailman.mit.edu/mailman/listinfo/mosh-users +.hy +. diff --git a/man/mosh.1 b/man/mosh.1 new file mode 100644 index 0000000..2a988a7 --- /dev/null +++ b/man/mosh.1 @@ -0,0 +1,109 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH MOSH 1 "February 2012" +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.SH NAME +mosh \- mobile shell with roaming and intelligent local echo +.SH SYNOPSIS +.B mosh +.RI [ options ] +[user@]host +.br +.SH DESCRIPTION +\fBmosh\fP (mobile shell) is a remote terminal application that +supports intermittent connectivity, allows roaming, and provides +speculative local echo and line editing of user keystrokes. + +Compared with \fBssh\fP, \fBmosh\fP is more robust \(em its +connections stay up across sleeps and changes in the client's IP +address \(em and more responsive, because the protocol is tolerant of +packet loss and the client can echo most keystrokes immediately, +without waiting for a network round-trip. + +\fBmosh\fP uses \fBssh\fP to establish a connection to the remote host +and authenticate with existing means (e.g., public-key authentication +or a password). \fBmosh\fP executes the unprivileged \fBmosh-server\fP +helper program on the server, then closes the SSH connection and +starts the \fBmosh-client\fP, which establishes a long-lived datagram +connection over UDP. + +To improve responsiveness, \fBmosh\fP runs a predictive model of the +server's behavior in the background, trying to guess the effect of +each keystroke on the screen. It makes predictions for normal typing, +backspace, and the left- and right-arrow keys. When it is confident, +\fBmosh\fP displays the predictions without waiting for the +server. The predictive model must prove itself anew on each row of the +terminal and after each control character, so \fBmosh\fP avoids +echoing passwords or non-echoing editor commands. + +By default, \fBmosh\fP shows its predictions only on high-latency +connections and to smooth out network glitches. (On longer-latency +links, the predicted cells are underlined until confirmed by the +server.) Occasional echo mistakes are corrected within a network +round-trip and do not cause lasting effect. + +\fBmosh\fP does not support X forwarding or the non-interactive uses +of SSH, including port forwarding or sshfs. \fBmosh\fP works through +typical client-side network address translators but requires high-port +UDP to pass between client and server. + +.SH OPTIONS +.TP +.B \-\-client=\fIPATH\fP +path to client helper on local machine (default: "mosh-client") + +.TP +.B \-\-server=\fIPATH\fP +path to server helper on remote machine (default: "mosh-server") + +The server helper is unprivileged and can be installed in the user's +home directory. + +.TP +.B \-\-predict=\fIWHEN\fP +Controls use of speculative local echo. WHEN defaults to `adaptive' +(show predictions on slower links and to smooth out network glitches) +and can also be `always` or `never'. + +The MOSH_PREDICTION_DISPLAY environment variable controls this setting +permanently and can adopt the same three values. + +Even on `always', \fBmosh\fP will only show predictions when it is +confident. This generally means a previous prediction on the same row +of the terminal has been confirmed by the server, without any +intervening control character keystrokes. + +.SH SEE ALSO +.BR mosh-client (1), +.BR mosh-server (1). + +Project home page: +.I http://mosh.mit.edu + +.br +.SH AUTHOR +mosh was written by Keith Winstein . +.SH BUGS +\fBmosh\fP is beta software. Please report bugs to \fImosh-devel@mit.edu\fP. Users may also subscribe +to the +.nh +.I mosh-users@mit.edu +.hy +mailing list, at +.nh +.I http://mailman.mit.edu/mailman/listinfo/mosh-users +.hy +.