All pages
Powered by GitBook
1 of 3

MySQL

Advanced configuration of MySQL connection type

Overview

The MySQL implementation in Keeper Connection Manager utilizes the MySQL client library as well as an internal terminal library which renders the user interface. Guacamole's MySQL support emulates a terminal on the server side, and draws the screen of this terminal remotely on the client.

This document is intended to cover all supported parameters, grouped in the same way they are grouped within the web interface. The field headings which would appear in the web interface are provided for each parameter, along with each parameter's internal name and a thorough description of the behavior and legal values for that parameter.

Keeper Secrets Manager parameters

Field header
Parameter name
Description

Allow user-provided KSM configuration:

ksm-user-config-enabled

If set to "true", each Keeper Connection Manager user profile can be assigned to a Keeper Secrets Manager configuration for any connection. See the Multiple Vaults Integration screen for more information.

Network parameters

MySQL connections are established over TCP to a specific port and a specific hostname or IP address. The hostname/address must be specified for all MySQL connections, but you only need to specify a port if you are not using the standard MySQL port (3306).

Field header (web interface)
Parameter name
Description

Hostname

hostname

REQUIRED: The hostname or IP address of the MySQL server Guacamole should connect to.

Port

port

The port the MySQL server is listening on. By default, the standard MySQL port of 3306 will be used.

Unix Socket

unix-socket

The socket name used for MySQL connections when running using the unix socket method. This is used if the host field is empty.

Authentication parameters

Keeper Connection manager supports MySQL authentication through username and password parameters. Both fields are required to establish a connection.

Authentication Parameters
Field header (web interface)
Parameter name
Description

Username

username

REQUIRED: The username to authenticate as when connecting to the specified MySQL server.

Password

password

REQUIRED: The password to use when authenticating with the specified MySQL server.

Database parameters

The default database can be specified when establishing the connection. You can also disable the ability to perform CSV import and export of data.

Field header (web interface)
Parameter name
Description

Default Database

database

The database schema selected when connecting to the specified MySQL server.

Disable CSV Export

disable-csv-export

Set this value to "true" to disable CSV export of data when using the SQL statement "select ... into local outfile"

Disable CSV Import

disable-csv-import

Set this value to "true" to disable CSV import of data when using the SQL statement "load data local infile ... into table"

Display settings

Guacamole's MySQL support provides a display, but not in the same sense as a remote desktop protocol like VNC or RDP. The display is a terminal emulator, and thus provides options for configuring the font used and its size.

If selecting a different font for a MySQL connection, the chosen font must be installed on the server running guacd. It is the server that will handle rendering of characters to the terminal display, not the client.

Display settings
Field header (web interface)
Parameter name
Description

Theme

color-scheme

The color scheme to use for the terminal emulator used by SSH connections. Each color scheme dictates the default foreground and background color for the terminal. Programs which specify colors when printing text will override these defaults. Legal values are:

  • "black-white" - Black text over a white background

  • "gray-black" - Gray text over a black background (the default)

  • "green-black" - Green text over a black background

  • "white-black" - White text over a black background

  • A custom color scheme (as described below)

By default, Guacamole will render text as gray over a black background.

Font name

font-name

The name of the font to use. If not specified, the default of "monospace" will be used instead. This must be the name of a font installed on the server running guacd, and should be a monospaced font. If a non-monospaced font is used, individual glyphs may render incorrectly.

Font size

font-size

The size of the font to use, in points. By default, the size of rendered text will be 12 point.

Maximum scrollback size:

scrollback

The maximum number of rows to allow within the terminal scrollback buffer. By default, the scrollback buffer will be limited to a maximum of 1000 rows.

Read-only:

read-only

Whether this connection should be read-only. If set to "true", no input will be accepted on the connection at all. Users will be able to see the terminal (or the application running within the terminal) but will be unable to interact.

Custom color schemes

Custom color schemes may be provided for the terminal emulator used by MySQL connections. Custom schemes mimic the format used by Xterm and consist of a semicolon-separated series of name-value pairs. Each name-value pair is separated by a colon and assigns a value to a color in the terminal emulator palette.

For example, to use blue text on white background by default, and change the red color to a purple shade, you would specify:

foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80

Legal color names are:

  • "foreground" - the default foreground color.

  • "background" - the default background color.

  • "colorN" - the color at index N within the Xterm 256-color palette. For example, "color9" refers to the color at palette index 9, normally red.

Legal color values are:

  • "rgb:RR/GG/BB" - a color in RGB format, with each component in hexadecimal. For example, "rgb:ff/00/00" specifies the color red. Each hexadecimal component may be one to four digits, but the effective values are always zero-extended or truncated to two digits; for example, "rgb:f/8/0", "rgb:f0/80/00", and "rgb:f0f/808/00f" all refer to the same effective color.

  • "colorN" - the color currently assigned to index N within the Xterm 256-color palette. For example, "color9" specifies the color currently assigned to palette index 9. Note that the current color value is used rather than a reference to that color. If the referenced color is changed later in the color scheme configuration, that new color value will not be reflected in this assignment.

  • "NAME" - the color with human-readable name "NAME", where "NAME" is one of the standard color names supported by X11. These names generally correspond to the names standardized by the W3C for CSS.

Clipboard parameters

Guacamole provides bidirectional access to the clipboard by default for MySQL connections. This behavior can be overridden on a per-connection basis, restricting access to the clipboard.

Clipboard parameters
Field header (web interface)
Parameter name
Description

Disable copying from terminal:

disable-copy

If set to "true", text copied within the MySQL session will not be accessible by the user at the browser side of the Guacamole session, and will be usable only within the remote desktop. By default, the user will be given access to the copied text.

Disable pasting from client:

disable-paste

If set to "true", text copied at the browser side of the Guacamole session will not be accessible within the MySQL session. By default, the user will be able to paste data from outside the browser within the MySQL session.

Text session recording (typescripts)

The full, raw text content of MySQL sessions, including timing information, can be recorded automatically to a specified directory. This recording, also known as a "typescript", will be written to two files within the directory specified: one file contains the raw text data, and the other contains timing information. Where "NAME" is the value provided for the typescript name, these files will be named "NAME" and "NAME.timing" respectively.

This format is compatible with the format used by the standard UNIX script command, and can be replayed using scriptreplay (if installed). For example, to replay a typescript called "NAME", you would run:

$ scriptreplay NAME.timing NAME
Typescript settings
Field header (web interface)
Parameter name
Description

Typescript path

typescript-path

The directory in which typescript files should be created. If a typescript needs to be recorded, then this parameter is required. Specifying this parameter enables typescript recording. If this parameter is omitted, no typescript will be recorded.

Typescript name

typescript-name

The base filename to use for any created recordings. If omitted, the base filename "typescript" will be used.

Guacamole will never overwrite an existing typescript. If necessary, a numeric suffix like ".1", ".2", ".3", etc. will be appended to the base filename to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the typescript will not be recorded, and an error will be logged.

This parameter only has an effect if typescript recording is enabled, which is controlled by specifying a typescript path. If the typescript path is not specified, recording of typescripts will not be enabled, and this parameter will be ignored.

Automatically create typescript path

create-typescript-path

If set to "true", the final directory within the specified typescript path will automatically be created if it does not yet exist. By default, no part of the typescript path will be automatically created, and any attempt to use a non-existent directory will result in the typescript not being recorded and an error being logged.

Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the typescript will not be recorded, and an error will be logged.

This parameter only has an effect if typescript recording is enabled, which is controlled by specifying a typescript path. If the typescript path is not specified, recording of typescripts will not be enabled, and this parameter will be ignored.

Screen recording parameters

MySQL sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently played back using the Glyptodon Enterprise Session Recording Player application hosted at player.glyptodon.com (or using a local deployment of this application).

The player is a static web application, using only JavaScript to play back provided recordings. This functionality is implemented strictly locally; the recordings are not uploaded to a remote service for processing. If you would prefer to use your own deployment of this application, or would like to investigate the source, the full source of the Glyptodon Enterprise Session Recording Player can be found on GitHub, along with instructions for local deployment: https://github.com/glyptodon/glyptodon-enterprise-player

The latest version of Keeper Connection Manager supports on-screen playback of recorded sessions. See the Session Recording documentation page.

Field header (web interface)
Parameter name
Description

Recording path

recording-path

The directory in which screen recording files should be created. If a graphical recording needs to be created, then this parameter is required. Specifying this parameter enables graphical screen recording. If this parameter is omitted, no graphical recording will be created.

Recording name

recording-name

The filename to use for any created recordings. If omitted, the filename of each recording will simply be "recording".

Guacamole will never overwrite an existing recording. If necessary, a numeric suffix like ".1", ".2", ".3", etc. will be appended to the filename to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the session will not be recorded, and an error will be logged.

This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

Exclude graphics/streams

recording-exclude-output

If set to "true", graphical output and other data normally streamed from server to client will be excluded from the recording, producing a recording which contains only user input events. By default, graphical output will be included in the recording.

This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

Exclude mouse

recording-exclude-mouse

If set to "true", user mouse events will be excluded from the recording, producing a recording which lacks a visible mouse cursor. By default, mouse events will be included in the recording.

This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

Include key events

recording-include-keys

If set to "true", user key events will be included in the recording. The recording can subsequently be passed through the guaclog utility to produce a human-readable interpretation of the keys pressed during the session. By default, for privacy's sake, key events will be NOT included in the recording.

This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

Automatically create recording path

create-recording-path

If set to "true", the final directory within the specified recording path will automatically be created if it does not yet exist. By default, no part of the recording path will be automatically created, and any attempt to use a non-existent directory will result in the session not being recorded and an error being logged.

Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the session will not be recorded, and an error will be logged.

This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

Importing and Exporting

Data can be imported to a MySQL connection from a file on your machine, or exported and downloaded to you machine.

Import

Import data from a file on your machine into the MySQL connection.

To import data from a csv file, is the LOAD DATA MySQL command:

LOAD DATA LOCAL INFILE "input.csv" INTO TABLE <table> FIELDS
  TERMINATED BY ',' ENCLOSED BY '"' LINES TERMINATED BY '\r\n'

In the example above, "<table>" should be replaced with the SQL table to import data into. The other parts of the command are required for CSV-formatted files. If your uploaded file uses different termination characters update the query accordingly.

After running the query, Keeper Connection Manager will prompt you to supply the data file. To upload the file, simply drag and drop it from your machine onto the browser window.

The file uploaded does not have to have the same name given in the query

Export

Data from the connected MySQL database can be exported to a file on your machine. To do this, use the following query:

 SELECT <query> INTO LOCAL OUTFILE "<name>.csv"

The result of the given <query> will be put into a CSV file with the given name and downloaded from the browser to your machine.

Keyboard Shortcuts

Keeper Connection Manager MySQL connections utilize EMACS-like commands for more powerful text editing. In order to utilize all of these commands, shortcuts are bound to specific Commands.

Note that some shortcuts may be captured by your browser, browser extensions, operating system, or other applications

Common Actions

Copy and Paste

To copy a region of text, first you need to select the text. The easiest way to do this is to highlight the text using your mouse curser.

To Copy

The copy command is Ctrl-c or Meta-w

Hold the Ctrl key and press the c key or press and release the ESC key then press and release the w key.

To Paste

The Paste command is sometimes referred to as 'Yank' and is activated with Ctrl-v or Ctrl-Y

Hold the Ctrl key and press the v key or press and hold Ctrl the click the y key.

Move to Beginning or End of Line

The cursor can be moved to the beginning or the end of the current line.

Move to Beginning

This command is done with Ctrl-A or the Home key

Click Home or hold the Ctrl key and hit the a key

Move to End

This command is done with Ctrl-E or the End key

Click End or hold the Ctrl key and hit the e key

Complete List of Shortcuts

See the complete list of available commands and shortcuts below.

In this table "Meta-" refers to hitting the ESC key followed by the shown key. For example to use Meta-B (ed-prev-word) hit ESC then release, then hit B and release. Optionally a Meta key can be setup on your keyboard.

Shortcut

Editor Command

Ctrl-@, NUL

set cursor where the mouse is located

Ctrl-A

move cursor to beginning of line

Ctrl-B

move cursor back one character

Ctrl-C

clear the terminal

Ctrl-D

close the current connection

Ctrl-E

move cursor to end of line

Ctrl-F

move cursor one character forward

Ctrl-H, Backspace

delete previous character

Ctrl-J, LF

newline

Ctrl-K

cut line

Ctrl-L, FF

clear screen

Ctrl-M, CR

newline

Ctrl-N

next history

Ctrl-O

tty flush output

Ctrl-P

previous history

Ctrl-Q

tty start output

Ctrl-R

redisplay

Ctrl-S

tty stop output

Ctrl-T

transpose characters

Ctrl-U

cut line

Ctrl-V

quoted insert

Ctrl-W

cut highlighted region

Ctrl-X

sequence lead in

Ctrl-Y

yank (paste)

Ctrl-Z, TSTP

tty sigtstp

Ctrl-[, ESC

move cursor forward

Ctrl-\, QUIT

tty sigquit

Ctrl-]

tty dsusp

Ctrl-?, DEL

delete previous character

Ctrl-Meta-H

delete previous word

Ctrl-Meta-L

clear screen

Ctrl-Meta-_

copy the previous word

Meta-0 to Meta-9

argument digit

Meta-B

previous word

Meta-C

use capitol case

Meta-D

delete next word

Meta-F

move to next word

Meta-L

lower case

Meta-N

search next history

Meta-O

sequence lead in

Meta-P

search previous history

Meta-U

upper case

Meta-W

copy highlighted region

Meta-X

command

Meta-[

sequence lead in

Meta-p

search previous history

Ctrl-Meta-?

delete previous word