commit built man pages

makes it easier to build/install without ruby

rsh.1

@@ -0,0 +1,187 @@
+.ad l
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "RSH" "1" "October 2017" "" ""
+.
+.SH "NAME"
+\fBrsh\fR \- Rancher SHell
+.
+.SH "SYNOPSIS"
+\fBrsh\fR [\fB\-GqTtv\fR] [\fB\-E\fR \fIlog_file\fR] [\fB\-e\fR \fIchar\fR] [\fB\-F\fR \fIconfig_file\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-l\fR \fIlogin_name\fR] [\fB\-o\fR \fIopt\fR] [\fB\-p\fR \fIport\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIprotocol\fR://][\fIuser\fR@]\fIhost\fR[:\fIport\fR][[/\fIenvironment\fR]/\fIstack\fR]/\fIservice\fR [\fIcommand\fR]
+.
+.SH "DESCRIPTION"
+\fBrsh\fR aims to replicate the features and experience of ssh, but for docker containers running within Rancher, as such it is a program for connecting into a remote container and for executing commands on a remote container\.
+.
+.P
+\fBrsh\fR queries the Rancher API at \fIhost\fR to find a container within the specified \fIenvironment\fR, \fIstack\fR, and \fIservice\fR then connects to the first available container\.
+.
+.P
+If \fIcommand\fR is specified, it is executed on the remote host instead of a login shell\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-E\fR \fIlog_file\fR
+Append debug logs to \fIlog_file\fR instead of standard error\.
+.
+.TP
+\fB\-e\fR \fIchar\fR
+Sets the escape character for sessions with a pty (default: \'~\')\. The escape character is only recognised at the beginning of a line\. The escape character followed by a dot (\'\.\') closes the connection; followed by control\-Z suspends the connection; and followed by itself sends the escape character once\. Setting the character to "none" disables any escapes and makes the session fully transparent\.
+.
+.TP
+\fB\-F\fR \fIconfig_file\fR
+Specifies an alternative per\-user configuration file\. If a configuration file is given on the command line, the system\-wide configuration file (\fI/etc/rsh/rsh_config\fR) will be ignored\. The default for the per\-user configuration file is \fI~/\.rsh/config\fR\.
+.
+.TP
+\fB\-G\fR
+Causes \fBrsh\fR to print its configuration after evaluating Host blocks and exit\.
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Causes \fBrsh\fR to print a short help message and exit\.
+.
+.TP
+\fB\-l\fR \fIlogin_name\fR
+Specifies the user to log in as on the remote machine\. This also may be specified on a per\-host basis in the configuration file\.
+.
+.TP
+\fB\-o\fR \fIopt\fR
+Can be used to give options in the format used in the configuration file\. This is useful for specifying options for which there is no separate command\-line flag\. For full details of the options listed below, and their possible values, see rsh_config(5)\.
+.
+.IP "" 4
+.
+.nf
+
+Environment
+EscapeChar
+HostName
+LogLevel
+Port
+Protocol
+RemoteCommand
+RequestTty
+SendEnv
+Service
+Stack
+User
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fB\-p\fR \fIport\fR
+Port to connect to on the remote host\. This can be specified on a per\-host basis in the configuration file\.
+.
+.TP
+\fB\-q\fR
+Quiet mode\. Causes most warning and diagnostic messages to be suppressed\.
+.
+.TP
+\fB\-T\fR
+Disable pseudo\-terminal allocation\.
+.
+.TP
+\fB\-t\fR
+Force pseudo\-terminal allocation\. This can be useful when executing a shell or console program directly, rather than performing a login\. Multiple \fB\-t\fR options force tty allocation, even if rsh has no local tty\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Display the version number and exit\.
+.
+.TP
+\fB\-v\fR
+Verbose mode\. Causes \fBrsh\fR to print debugging messages about its progress\. This is helpful in debugging connection, authentication, and configuration problems\. Multiple \fB\-v\fR options increase the verbosity\. The maximum is 3\.
+.
+.SH "EXAMPLES"
+Start a login shell as the \fIroot\fR user on a container in the \fIapi\fR service of the \fIweb\fR stack in the \fIproduction\fR environment of \fIhttps://example\.com\fR\. The current directory will be the home directory of the root user:
+.
+.IP "" 4
+.
+.nf
+
+rsh https://root@example\.com/production/web/api
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Execute a shell directly on a container in the \fIapi\fR service of the \fIweb\fR stack in the \fIproduction\fR environment of \fIhttps://example\.com\fR\. The user and working directory will match those configured in the service\'s Dockerfile:
+.
+.IP "" 4
+.
+.nf
+
+rsh \-t https://example\.com/production/web/api /bin/sh
+.
+.fi
+.
+.IP "" 0
+.
+.SH "AUTHENTICATION"
+Upon first connecting to a Rancher server that requires authentication \fBrsh\fR will request a username and password to log into the Rancher server\. It will then create a user API key, and save this to \fI~/\.rsh/\fIhost\fR\fR, using the API key for all further requests\.
+.
+.P
+Currently only LDAP authenticated and unauthenticated Rancher servers have been tested\.
+.
+.SH "ESCAPE CHARACTERS"
+When a pseudo\-terminal has been requested, \fBrsh\fR supports a number of functions through the use of an escape character\.
+.
+.P
+A single tilde character can be sent as ~~ or by following the tilde by a character other than those described below\. The escape character must always follow a newline to be interpreted as special\. The escape character can be changed in configuration files using the \fBEscapeChar\fR configuration directive or on the command line by the \fB\-e\fR option\.
+.
+.P
+The supported escapes (assuming the default \'~\') are:
+.
+.TP
+\fB~\.\fR
+Disconnect\.
+.
+.TP
+\fB~^Z\fR
+Background rsh\.
+.
+.TP
+\fB~?\fR
+Display a list of escape characters\.
+.
+.TP
+\fB~V\fR
+Decrease the verbosity (\fBLogLevel\fR) when errors are being written to stderr\.
+.
+.TP
+\fB~v\fR
+Increase the verbosity (\fBLogLevel\fR) when errors are being written to stderr\.
+.
+.SH "FILES"
+.
+.TP
+\fB~/\.rsh/\fR
+This directory is the default location for all user\-specific configuration and authentication information\.
+.
+.TP
+\fB~/\.rsh/config\fR
+This is the per\-user configuration file\. The file format and configuration options are described in rsh_config(5)\.
+.
+.TP
+\fB/etc/rsh/rsh_config\fR
+Systemwide configuration file\. The file format and configuration options are described in rsh_config(5)\.
+.
+.SH "ENVIRONMENT"
+\fBrsh\fR will normally set the following environment variables:
+.
+.TP
+\fBTERM\fR
+Set to the value of \fBTERM\fR on the client machine\.
+.
+.P
+Additional environment variables can be forwarded by setting the \fBSendEnv\fR option in rsh_config(5)\.
+.
+.SH "AUTHORS"
+\fBavvoenv\fR is heavily inspired by OpenSSH, and portions of the man page have been directly copied\. It is written and maintained by the Avvo Infrastructure Team \fIinfrastructure@avvo\.com\fR\.
+.
+.SH "SEE ALSO"
+rsh_config(5)

rsh_config.5

@@ -0,0 +1,194 @@
+.ad l
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "RSH_CONFIG" "5" "October 2017" "" ""
+.
+.SH "NAME"
+\fBrsh_config\fR \- rsh configuration
+.
+.SH "SYNOPSIS"
+\fB~/\.rsh/config\fR
+.
+.br
+\fB/etc/rsh/rsh_config\fR
+.
+.SH "DESCRIPTION"
+rsh(1) obtains configuration data from the following sources in the following order:
+.
+.IP "1." 4
+command\-line options
+.
+.IP "2." 4
+user\'s configuration file (\fI~/\.rsh/config\fR)
+.
+.IP "3." 4
+system\-wide configuration file (\fI/etc/rsh/rsh_config\fR)
+.
+.IP "" 0
+.
+.P
+For each parameter, the first obtained value will be used\. The configuration files contain sections separated by Host specifications, and that section is only applied for hosts that match one of the patterns given in the specification\. The matched host name is the complete \fIprotocol://user@host:port/env/stack/service\fR line given on the command line\.
+.
+.P
+Since the first obtained value for each parameter is used, more host\-specific declarations should be given near the beginning of the file, and general defaults at the end\.
+.
+.P
+The file contains keyword\-argument pairs, one per line\. Lines starting with \'#\' and empty lines are interpreted as comments\. Arguments may optionally be enclosed in double quotes (") in order to represent arguments containing spaces\. Configuration options may be separated by whitespace or optional whitespace and exactly one \'=\'; the latter format is useful to avoid the need to quote whitespace when specifying configuration options using \fB\-o\fR\.
+.
+.P
+The possible keywords and their meanings are as follows (note that keywords are case\-insensitive and arguments are case\-sensitive):
+.
+.TP
+\fBHost\fR
+Restricts the following declarations (up to the next \fBHost\fR keyword) to be only for those hosts that match one of the patterns given after the keyword\. If more than one pattern is provided, they should be separated by whitespace\. A single \'*\' as a pattern can be used to provide global defaults for all hosts\. The host is the complete \fIprotocol://user@host:port/env/stack/service\fR line given on the command line\.
+.
+.IP
+A pattern entry may be negated by prefixing it with an exclamation mark (\'!\')\. If a negated entry is matched, then the \fBHost\fR entry is ignored, regardless of whether any other patterns on the line match\. Negated matches are therefore useful to provide exceptions for wildcard matches\.
+.
+.IP
+See \fIPATTERNS\fR for more information on patterns\.
+.
+.TP
+\fBEnvironment\fR
+Specifies the Rancher environment of the container to log in to\. Arguments to \fBEnvironment\fR accept the tokens described in the \fITOKENS\fR section\. The default is the name given on the command line\.
+.
+.TP
+\fBEscapeChar\fR
+Sets the escape character (default: \'~\')\. The escape character can also be set on the command line\. The argument should be a single character, or \fBnone\fR to disable the escape character entirely (making the connection transparent for binary data)\.
+.
+.TP
+\fBHostName\fR
+Specifies the real host name to log into\. This can be used to specify nicknames or abbreviations for hosts\. Arguments to \fBHostName\fR accept the tokens described in the \fITOKENS\fR section\. Numeric IP addresses are also permitted (both on the command line and in \fBHostName\fR specifications)\. The default is the name given on the command line\.
+.
+.TP
+\fBLogLevel\fR
+Gives the verbosity level that is used when logging messages from rsh(1)\. The possible values are: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3\. The default is INFO\. DEBUG and DEBUG1 are equivalent\. DEBUG2 and DEBUG3 each specify higher levels of verbose output\.
+.
+.TP
+\fBPort\fR
+Specifies the port number to connect on the remote host\. The default is 80 if the protocol is http, or 443 if the protocol is https\.
+.
+.TP
+\fBProtocol\fR
+Specifies the protocol used to connect on the remote host\. The argument may be one of \fBhttp\fR or \fBhttps\fR\. The default is \fBhttps\fR\.
+.
+.TP
+\fBRemoteCommand\fR
+Specifies the command to execute on the remote host instead of a login shell\. Arguments to \fBRemoteCommand\fR accept the tokens described in the \fITOKENS\fR section\. This can also be specified with the final argument on the command line\.
+.
+.TP
+\fBRequestTTY\fR
+Specifies whether to request a pseudo\-tty for the session\. The argument may be one of: \fBno\fR (never request a TTY), \fByes\fR (always request a TTY when standard input is a TTY), \fBforce\fR (always request a TTY) or \fBauto\fR (request a TTY when opening a login session)\. This option mirrors the \fB\-t\fR and \fB\-T\fR flags for rsh(1)\.
+.
+.TP
+\fBSendEnv\fR
+Specifies what variables from the local environ(7) should be sent to the server\. Note that the TERM environment variable is always sent whenever a pseudo\-terminal is requested as it is required by the protocol\. Variables are specified by name, which may contain wildcard characters\. Multiple environment variables may be separated by whitespace or spread across multiple SendEnv directives\. The default is not to send any environment variables\.
+.
+.IP
+See \fIPATTERNS\fR for more information on patterns\.
+.
+.TP
+\fBService\fR
+Specifies the Rancher service of the container to log in to\. Arguments to \fBService\fR accept the tokens described in the \fITOKENS\fR section\. The default is the name given on the command line\.
+.
+.TP
+\fBStack\fR
+Specifies the Rancher stack of the container to log in to\. Arguments to \fBStack\fR accept the tokens described in the \fITOKENS\fR section\. The default is the name given on the command line\.
+.
+.TP
+\fBUser\fR
+Specifies the user to log in as\. This can be useful when a different user name is used on different containers\. This saves the trouble of having to remember to give the user name on the command line\.
+.
+.SH "PATTERNS"
+A pattern consists of zero or more non\-whitespace characters, \'*\' (a wildcard that matches zero or more characters), or \'?\' (a wildcard that matches exactly one character)\. For example, to specify a set of declarations for any host in the "\.co\.uk" set of domains, the following pattern could be used:
+.
+.IP "" 4
+.
+.nf
+
+Host *\.co\.uk/*
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The following pattern would match any host in the 192\.168\.0\.[0\-9] network range:
+.
+.IP "" 4
+.
+.nf
+
+Host *192\.168\.0\.?/*
+.
+.fi
+.
+.IP "" 0
+.
+.P
+A pattern\-list is a comma\-separated list of patterns\. Patterns within pattern\-lists may be negated by preceding them with an exclamation mark (\'!\')\. For example, to match all hosts except production the following entry could be used:
+.
+.IP "" 4
+.
+.nf
+
+Host !*prod\.example\.com/*,*\.example\.com/*
+.
+.fi
+.
+.IP "" 0
+.
+.SH "TOKENS"
+Arguments to some keywords can make use of tokens, which are expanded at runtime:
+.
+.IP "" 4
+.
+.nf
+
+      %%    A literal \'%\'\.
+      %e    The remote environment\.
+      %h    The remote hostname\.
+      %r    The remote username\.
+      %S    The remote stack\.
+      %s    The remote service\.
+.
+.fi
+.
+.IP "" 0
+.
+.TP
+\fBEnvironment\fR
+accepts the tokens %%, %e, $S, and %s\.
+.
+.TP
+\fBHostName\fR
+accepts the tokens %%, and %h\.
+.
+.TP
+\fBRemoteCommand\fR
+accepts the tokens %%, and %r\.
+.
+.TP
+\fBStack\fR
+accepts the tokens %%, %e, $S, and %s\.
+.
+.TP
+\fBService\fR
+accepts the tokens %%, %e, $S, and %s\.
+.
+.SH "FILES"
+.
+.TP
+\fB~/\.rsh/config\fR
+This is the per\-user configuration file\. The file format and configuration options are described above\.
+.
+.TP
+\fB/etc/rsh/rsh_config\fR
+Systemwide configuration file\. The file format and configuration options are described above\.
+.
+.SH "AUTHORS"
+\fBavvoenv\fR is heavily inspired by OpenSSH, and portions of the man page have been directly copied\. It is written and maintained by the Avvo Infrastructure Team \fIinfrastructure@avvo\.com\fR\.
+.
+.SH "SEE ALSO"
+rsh(1)