README
¶
Bring
Go client library for Apache Guacamole Protocol.
Quick start (tl;dr)
-
Install the library in your project:
go get github.com/deluan/bring -
Create a Client with the NewClient() function. This creates a session with the specified
guacdserver -
Start the client with
go client.Start() -
Get screen updates with
client.Screen() -
Send keystrokes with
client.SendKey() -
Send mouse updates with
client.SendMouse()
See the sample app for a working example
Documentation
The API is provided by the Session and the Client structs. The documentation is a work in progress, but the API is very simple and you can take a look at all features available in the sample app provided. Here are the steps to run the app:
-
You'll need a working
guacdserver in your machine. The easiest way is using docker and docker-compose. Just calldocker-compose up -din the root of this project. It starts theguacdserver and a sample headless linux with a VNC server -
Run the sample app with
make run. It will connect to the linux container started by docker.
Take a look at the Makefile to learn how to run it in different scenarios.
Why?
Apache Guacamole was created with the goal of making a dedicated client unnecessary. So why create a client?!
The idea is that if you need to control a remote machine from your Go code, you can
leverage the Guacamole protocol and the guacd server as a bridge. This way you can
use any protocol supported by Guacamole (currently RDP and VNC, with X11 coming in
the future) to do screen capture and remote control of networked servers/desktop
machines from within your Go app.
My use case was to automate some tasks in a VirtualBox VM, but there was no Go support for the VirtualBox XPCOM API on Macs (my host platform), nor a working RDP client implementation in Go. Instead of writing a new RDP client, why not leverage the awesome Guacamole project and get support for multiple protocols?
References:
Documentation
¶
Overview ¶
Package bring implements a Guacamole client, with full remote control capabilities.
Index ¶
- Variables
- type Client
- func (c *Client) OnSync(f OnSyncFunc)
- func (c *Client) Screen() (image image.Image, lastUpdate int64)
- func (c *Client) SendKey(key KeyCode, pressed bool) error
- func (c *Client) SendMouse(p image.Point, pressedButtons ...MouseButton) error
- func (c *Client) SendText(sequence string) error
- func (c *Client) Start()
- func (c *Client) State() SessionState
- type DefaultLogger
- func (l *DefaultLogger) Debugf(format string, args ...interface{})
- func (l *DefaultLogger) Errorf(format string, args ...interface{})
- func (l *DefaultLogger) Infof(format string, args ...interface{})
- func (l *DefaultLogger) Tracef(format string, args ...interface{})
- func (l *DefaultLogger) Warnf(format string, args ...interface{})
- type KeyCode
- type Logger
- type MouseButton
- type OnSyncFunc
- type SessionState
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidKeyCode = errors.New("invalid key code")
var ErrNotConnected = errors.New("not connected")
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Guacamole protocol client. Automatically handles incoming and outgoing Guacamole instructions, updating its display using one or more graphic primitives.
func NewClient ¶
func NewClient(addr string, remoteProtocol string, config map[string]string, logger ...Logger) (*Client, error)
NewClient creates a Client and connects it to the guacd server with the provided configuration. Logger is optional
func (*Client) OnSync ¶ added in v0.0.4
func (c *Client) OnSync(f OnSyncFunc)
func (*Client) Screen ¶
Returns a snapshot of the current screen, together with the last updated timestamp
func (*Client) SendMouse ¶
func (c *Client) SendMouse(p image.Point, pressedButtons ...MouseButton) error
Send mouse events to the server. An event is composed by position of the cursor, and a list of any currently pressed MouseButtons
func (*Client) SendText ¶
Send the sequence of characters as they were typed. Only works with simple chars (no combination with control keys)
type DefaultLogger ¶
type DefaultLogger struct {
Quiet bool
}
Simple console logger
func (*DefaultLogger) Debugf ¶
func (l *DefaultLogger) Debugf(format string, args ...interface{})
func (*DefaultLogger) Errorf ¶
func (l *DefaultLogger) Errorf(format string, args ...interface{})
func (*DefaultLogger) Infof ¶
func (l *DefaultLogger) Infof(format string, args ...interface{})
func (*DefaultLogger) Tracef ¶
func (l *DefaultLogger) Tracef(format string, args ...interface{})
func (*DefaultLogger) Warnf ¶
func (l *DefaultLogger) Warnf(format string, args ...interface{})
type KeyCode ¶
type KeyCode int32
Keys recognized by guacd. ASCII symbols from 32 to 126 do not need mapping.
const ( KeyAgain KeyCode = 1024 + iota KeyAllCandidates KeyAlphanumeric KeyLeftAlt KeyRightAlt KeyAttn KeyAltGraph KeyArrowDown KeyArrowLeft KeyArrowRight KeyArrowUp KeyBackspace KeyCapsLock KeyCancel KeyClear KeyConvert KeyCopy KeyCrsel KeyCrSel KeyCodeInput KeyCompose KeyLeftControl KeyRightControl KeyContextMenu KeyDelete KeyDown KeyEnd KeyEnter KeyEraseEof KeyEscape KeyExecute KeyExsel KeyExSel KeyF1 KeyF2 KeyF3 KeyF4 KeyF5 KeyF6 KeyF7 KeyF8 KeyF9 KeyF10 KeyF11 KeyF12 KeyF13 KeyF14 KeyF15 KeyF16 KeyF17 KeyF18 KeyF19 KeyF20 KeyF21 KeyF22 KeyF23 KeyF24 KeyFind KeyGroupFirst KeyGroupLast KeyGroupNext KeyGroupPrevious KeyFullWidth KeyHalfWidth KeyHangulMode KeyHankaku KeyHanjaMode KeyHelp KeyHiragana KeyHiraganaKatakana KeyHome KeyHyper KeyInsert KeyJapaneseHiragana KeyJapaneseKatakana KeyJapaneseRomaji KeyJunjaMode KeyKanaMode KeyKanjiMode KeyKatakana KeyLeft KeyMeta KeyModeChange KeyNumLock KeyPageDown KeyPageUp KeyPause KeyPlay KeyPreviousCandidate KeyPrintScreen KeyRedo KeyRight KeyRomanCharacters KeyScroll KeySelect KeySeparator KeyLeftShift KeyRightShift KeySingleCandidate KeySuper KeyTab KeyUIKeyInputDownArrow KeyUIKeyInputEscape KeyUIKeyInputLeftArrow KeyUIKeyInputRightArrow KeyUIKeyInputUpArrow KeyUp KeyUndo KeyWin KeyZenkaku KeyZenkakuHankaku )
type Logger ¶
type Logger interface {
Tracef(format string, args ...interface{})
Debugf(format string, args ...interface{})
Infof(format string, args ...interface{})
Warnf(format string, args ...interface{})
Errorf(format string, args ...interface{})
}
Logger interface used by this package. It is compatible with Logrus, but anything implementing this interface can be used
type MouseButton ¶
type MouseButton int
Mouse buttons recognized by guacd
const ( MouseLeft MouseButton = 1 << iota MouseMiddle MouseRight MouseUp MouseDown )
type OnSyncFunc ¶ added in v0.0.4
type SessionState ¶
type SessionState int
const ( SessionClosed SessionState = iota SessionHandshake SessionActive )
Source Files
Directories