User guide for Mocha X11

How it works
Getting started
Configure X11
Configure a client
User interface
Solving connection problems

How it works

Mocha X11 uses a client-server model: The Mocha X11 terminal communicates with various client programs on Linux/UNIX Servers. Mocha X11 accepts requests for graphical windows and sends back user input from keyboard and mouse.

Mocha X11 will listen on TCP port 6000 for any clients. On the iPhone/iPad running Mocha X11, start a client inside Mocha X11. This client will use Telnet or SSH, to establish a session to the remote Server.
After user validation, it will start an X11 application on the Server. This X11 application can make a connection back to Mocha X11 on port 6000, and request Mocha X11 to open a window.

It is also possible to use a SSH tunnel to route all X11 traffic in a secure way. The SSH tunnel will also makes it possible to access a Server from a device on another network, such as an iPhone using only a cell network.

Example A: Mocha X11 at IP 192.168.1.21:

Mocha		LINUX SERVER
SSH/Telnet	---------->	Start xterm DISPLAY=192.168.1.21:0
Listen	<----------	Connect to 192.168.1.21:6000
	<----------	Send X11 data
Display xterm

Example B: Mocha X11 on an iPhone using Cell network:

Mocha		LINUX SERVER
SSH	---------->	Make SSH tunnel with X forwarding
		SSH Server listen at port 6010
SSH	---------->	Start xterm, DISPLAY=localhost:10
	<----------	Send X11 data using the tunnel
Display xterm

Getting started

In most cases there is not any need to configure the X11 Terminal. If clients should not be started direct from the UNIX/Linux server, first a set of clients must be configured. See Configure a client

Hereafter click on "START" , and the Mocha X11 terminal will listen for traffic on port 6000. If a client should be started, click on the menu icon in the black banner:

If the client window is not displayed, use Client Log from the menu, and look for any error messages.

Configure X11 Terminal

X11 Port: Mocha X11 will listen on this port.
Keyboard: Type of keyboard on the server.
Screen size: For iPad a recommended size is 1280x1920, on an iPhone 1280x1024.
Desktop color: Background color for the desktop.
Key banner layout: Select which keys, and the position for keys in the horizontal key banner.
Wireless keyboard: Include limited support for a Mac wireless keyboard. The current iOS does not fully support the keyboard. F1-F12 cannot be used. Enable this option, if using the iPad Pro keyboard.
Auto lock: If NO, the screen will not lock as to save power, if YES, the auto lock configuration from the iOS is used.
Zoom to screen height: Either allow user to zoom out to full server screen height or screen width.
Give warning at window close: Display a warning, before closing a window.
Mouse button swap:Use right mouse button as middle button.
Right mouse beep:If right mouse button should give a beep.

Configure a client

Client IP: Name of the server, where the client application runs. Either a TCP/IP address as 155.22.11.2 or a DNS name.
Telnet or SSH:Type of protocol to use.
Close after 10 seconds: Some X11 UNIX programs can continue to run, even after the user session starting the application has terminated. An example is XTERM. A program as GIMP will terminate, and therefore, if GIMP is the client application, do not enable this option.
X11 Forwarding:Tunnel all X11 traffic inside the SSH sesssion. It gives security, and the SSH tunnel can also make it possible to access a UNIX/Linux server from a device with only Internet access.
Command: Command to issue after a successful user validation. Notice, if DISPLAY is used (see clients advanced configuration), there is no need to include parameters as -display or --display for the UNIX application.
To get a larger font for xterm, use fs parameter:

xterm -fa default -fs 24
User : This is the user name on the server. It is optional. The user name can also be typed, when starting the client.
Password : This is the password for the user on the server. It is optional. The password can also be typed, when starting the client.
Name: Give the session configuration a name, as it is easier to remember than the IP address.

In menu - Clients Advanced configuration are parameters valid for all clients:

Search for user ID : Text to look for, before sending the user id (only with telnet protocol).
Search for password : Text to look for from the server, before sending the password (only with telnet protocol).
Search for prompt : Text to look for from the server, before sending the command.
Return key : Octal value for the return key. Most server uses \012 or \015.
DISPLAY : Use a default DISPLAY settings with the command.
Telnet/SSH Port: Port number for the session. As default Telnet uses port 23 and SSH 22.
Send variable DISPLAY: send the DISPLAY command , before the command for the application on the server.

User interface

Windows

Select:Click the window. A Window with keyboard focus, has a dark blue title bar.
Move:First lock the screen using the lock icon in the black bar. Place a finger on the title bar, and it will change to color red, now drag the window to a new position.
Resize:Click the resize icon in the title bar, and the border change to color red. Drag the window to another size.
Close:Click the [x] close icon in the title bar.

Mouse

Left click: tap the screen.
Double click: tap the screen twice.
Right click:hold down finger 1 second on the screen. Can in menu - Configure X11 Terminal, be swapped to the middle button.
Drag mouse: Tap [drag] in the keyboard scroll banner. A double click makes drag enabled until another tap on [drag]. If the screen is locked, a finger on the screen is also mouse dragging.
Mouse over (hover): Tap [hover] in the keyboard scroll banner. A double click makes hover mode enabled until another tap on [hover]
Wheel: If the screen is locked (use the black banner lock icon), move 2 fingers up/down on the screen, or use [w-up] and [w-down] in the keyboard scroll banner.

Keyboard scroll banner

A scroll banner with extra keys can be shown on top of the normal keyboard, or using the extra keys icon (second from the left) in the black status bar for the window. Use the small arrow up at the right side of the banner to get a second banner on top. Keys [shift] [drag] and [hover] can be double clicked, as a lock function.
Hide the scroll banner with a tap on the [hide] button.

Black tool bar

QWERTY keyboard: Will pop up the normal iphone/ipad keyboard.
Extra keys: Show a scroll banner with extra keys and mouse functions.
Menu: Menu with access to clients, disconnect and other basic functions
Return key: An easy to use return key
Zoom out: Zoom the screen out. The menu - configure - zoom to height option, will select if the zoom should be to full server height or width.
Screen lock: Stop the screen from scrolling or zooming. A finger moving over the screen is now mouse dragging. With screen lock enabled, it is not possible to use mouse hover, but 2 fingers on the screen moving up/down works as mouse wheel.
Hide tool bar: Hides the tool bar. The small icon stays in the right corner, as to make it easy to show the full tool bar again.

Wireless keyboard: fn (f1-f12) cannot be used, but

ctrl+1 = f1
ctrl+2 = f2
ctrl+3 = f3
ctrl+4 = f4
ctrl+5 = f5
ctrl+6 = f6
ctrl+7 = f7
ctrl+8 = f8
ctrl+9 = f9
ctrl+0 = f10

Solving connection problems

If a client does not start, use menu - Client log to look for any error messages.

As default many UNIX/Linux servers will block port 23 and telnet. It will be easier to use SSH (Secure Shell). The Secure Shell client in Mocha X11 supports only password validation. Certificates are not supported.