= Connectors

Connectors manages the connection of the client to the shell.

== JVM connector

The jvm connector is used in the standalone mode and relies on the JVM streams (_System.in_, _System.out_ and
_System.err_).

The jvm connector uses the default platform encoding provided by the JVM.

The jvm connector uses some parts of the https://github.com/jline/jline2[JLine] library, since 1.3 it uses the
_terminal detection and configuration_ and the _key mapping_. The JLine library is shaded and included in the
_crash.shell_ jar: you don't need the JLine jar on your classpath and the included jar will not conflict
with another existing JLine jar.

JLine can be configured via system properties and the property names should be prefixed with +org.crsh.console+ as
the library is shaded.

=== Terminal detection

By default JLine autodetects the terminal based of the current operating system, the autodetection can be configured
to a more specific terminal type with the +org.crsh.console.jline.terminal+ property, see the JLine
https://github.com/jline/jline2/wiki/Terminal%20Factory%20Configuration[wiki].

TIP: running CRaSH an IDE terminal has limited capabilities and setting the system property
+org.crsh.console.jline.terminal=none+ will improve the user experience

=== JLine logging

JLine logging is useful for troubleshooting the terminal emulation, trace and debug can be activated with the
+org.crsh.console.jline.internal.Log.debug=true+ and +org.crsh.console.jline.internal.Log.trace=true+, see the
JLine https://github.com/jline/jline2/wiki/Logging%20Configuration[wiki]

== SSH connector

=== Changing the SSH server port

The ports of the server is parameterized by the _crash.ssh.port_ configuration property

----
crash.ssh.port=2000
----

=== Changing SSH server key

The key can be changed by replacing the file _WEB-INF/sshd/hostkey.pem_. Alternatively you can configure the server
to use an external file by using the _crash.ssh.keypath_ parameter in the _crash.properties_. Uncomment the corresponding
property and change the path to the key file.

----
#crash.ssh.keypath=/path/to/the/key/file
----

If you specify an external file, you can also configure the server to generate it for you. In this case, the generation
will take place when someone first connects through SSH. The default behavior is _false_, i.e. not to generate.

----
#crash.ssh.keygen=false
----

=== Changing SSH authentication and idle timeouts

Default authentication and idle timeout of the SSH server are set to 10 minutes (600'000 ms). Both timeouts can be
configured in milliseconds with the _crash.ssh.auth-timeout_ and _crash.ssh.idle-timeout_ parameters in the
_crash.properties_ file.

----
# SSH configuration 5 minutes = 5 * 60 * 1000 = 300'000
crash.ssh.auth_timeout=300000
crash.ssh.idle_timeout=300000
----

NOTE: those properties are named _crash.ssh.auth-timeout_ and _crash.ssh.idle-timeout_ in previous version.

=== Removing SSH access

To remove the SSH access, remove the jar file _crash.connectors.ssh-{crash-version}.jar_.

=== Character encoding

By default the SSH connector will uses the _LC_CTYPE_ env value set by the remote client. When this cannot be achieved
the SSH connector uses the _UTF-8_ as default encoding. This default value can be changed using the _crash.ssh.default_encoding_ configuration
property.

----
crash.ssh.default_encoding=UTF-8
----

== Telnet connector

=== Changing the Telnet server port

The ports of the server is parameterized by the _crash.telnet.port_ configuration property

----
crash.telnet.port=5000
----

=== Removing Telnet access

To remove the Telnet access, remove the jar file _crash.connectors.telnet-{crash-version}.jar_.

== Web connector

The websocket provides connectivity from a web browser through WebSockets based on:

- The jQuery Terminal Emulator Plugin
- a browser supporting WebSockets
- a Java web server implementing the JSR 356 API

=== Client setup

CRaSH.js is the client side part of the connector, it is built on top of the _jQuery Terminal Emulator Plugin_ and
 uses a client/server protocol for the shell connection.

The web page embedding _CRaSH.js_ requires a few assets:

[source,html]
----
<script src="js/jquery-1.7.1.min.js"></script>
<script src="js/jquery.mousewheel-min.js"></script>
<script src="js/jquery.terminal-0.7.12.js"></script>
<script src="js/crash.js"></script>
<link href="css/jquery.terminal.css" rel="stylesheet"/>
----

It can be setup in a few lines of JavaScript:

[source,javascript]
----

// Create web socket url
var path = window.location.pathname;
var ctx = path.substring(0, path.indexOf('/', 1));
var protocol;
if (window.location.protocol == 'http:') {
  protocol = 'ws';
} else {
  protocol = 'wss';
}
var url = protocol + '://' + window.location.host + ctx + '/crash';

// Connect to the server
var crash = new CRaSH($('#term_demo'), 1024, 768);
crash.connect(url);
----

=== Server setup

Currently the WebSocket server uses the JSR 356 API, the connector is bootstrapped by the +org.crashub:crash.connectors.web+ jar
that contains an annotation based endpoint bound to the _/crash_ uri. Therefore the full uri is prefixed by the web application
context path in which the connector is deployed.

The +org.crashub:crash.connectors.web+ jar contains also the assets for setting up the client side exposed automatically
when the jar is in the _WEB-INF/lib_ of the web application (they are located in the _META-INF/resources_ entry of the
jar). To activate the connector the property +crash.web.enabled+ must be set to +true+.

=== Step by step setup (recap)

- put the +org.crashub:crash.connectors.web+ jar in _WEB-INF/lib_
- add the +crash.web.enabled=true+ in _WEB-INF/crash/crash.properties_
- create a web page in your war file that contains the assets listed previously
- setup _crash.js_ in the page

=== Securing the server

todo