rcon

README

go-rcon

Minecraft RCON client module for connecting to Minecraft server using RCON protocol written in Go.

rcon.Client features a concurrent-safe Send function that creates a separate RCON connection for each command enabling asynchronous execution if desired. The ability to reuse a single connection is also available by creating rcon.Conn directly and sending commands via SendCommand function until the connection is closed.

Fragmented responses over 4096 bytes are also handled and parsed into single response.

This project is still under development and requires additional testing before it can be considered production ready.

Getting Started

Installing

go get will always pull the latest tagged release from the main branch.

go get github.com/jltobler/go-rcon

Usage

Import the package into your project.

import "github.com/jltobler/go-rcon"

Construct a new RCON client which can be used to access the send function.

rconClient := rcon.NewClient("rcon://localhost:25575", "password")

Use the Send function to request commands be remotely executed on the Minecraft server.

rconClient, err := rconClient.Send("time set day")

Documentation

Index

• Constants
• func Marshal(p *Packet) ([]byte, error)
• func Unmarshal(data []byte, p *Packet) error
• type Client
  • func NewClient(addr, password string) *Client
  • func (c *Client) Send(command string) (string, error)
• type Conn
  • func Dial(addr, password string) (*Conn, error)
  • func NewConn(c net.Conn, password string) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) IsClosed() bool
  • func (c *Conn) SendCommand(command string) (string, error)
• type Kind
• type Packet
  • func NewPacket(kind Kind, payload string) *Packet

Constants

const (
	DefaultPort uint16 = 25575
)

Functions

func Marshal

func Marshal(p *Packet) ([]byte, error)

Marshal returns the RCON encoding of Packet p. If Packet p is nil or contains invalid payload, Marshal returns an error.

func Unmarshal

func Unmarshal(data []byte, p *Packet) error

Unmarshal parses the RCON encoded Packet data and stores the result in the value pointed to by p. If p is nil or data contains invalid RCON encoding, Unmarshal returns an error.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client acts as the entrypoint to send RCON messages. Client hold all the configuration necessary to connect to Minecraft server.

func NewClient

func NewClient(addr, password string) *Client

NewClient creates and returns a configured RCON client.

func (*Client) Send

func (c *Client) Send(command string) (string, error)

Send establishes a new authenticated connection to the Minecraft server and transmits requested command. Not all commands generate a response from the server. Any response from the server is returned to requester. If connection failure occurs an error is returned.

This function is concurrency-safe since each command sent to the Minecraft server creates a new connection. Upon completion of the request the established connection is closed.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn represents a remote RCON connection to a Minecraft server.

The RCON connection allows server administrators to remotely execute commands on Minecraft servers.

func Dial

func Dial(addr, password string) (*Conn, error)

Dial connects and authenticates to the specified URL.

The underlying transport layer connection is created along with the configured RCON connection.

func NewConn

func NewConn(c net.Conn, password string) (*Conn, error)

NewConn wraps transport layer connection with RCON configuration.

RCON authentication is performed as part of connection configuration. Failed authentication closes the transport layer connection.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Any blocked command executions will be unblocked and return errors.

func (*Conn) IsClosed

func (c *Conn) IsClosed() bool

IsClosed returns whether the RCON connection is closed.

It is possible that an RCON connection becomes closed due to the server hanging up or other connection errors.

func (*Conn) SendCommand

func (c *Conn) SendCommand(command string) (string, error)

SendCommand sends RCON command to server and returns response.

Commands sent are processed sequentially and the next command cannot execute until the previous completes. All connection errors result in the connection being closed.

type Kind

type Kind uint32

const (
	ResponsePacket Kind = iota

	CommandPacket
	LoginPacket

	TerminationPacket
	TerminalResponse = "Unknown request 5"
)

Enumerates Packet types

type Packet

type Packet struct {
	Length  uint32
	ID      int32
	Kind    Kind
	Payload string
}

Packet defines RCON protocol encoding.

func NewPacket

func NewPacket(kind Kind, payload string) *Packet

NewPacket creates and returns a Packet. Packet length and ID are automatically set to satisfy protocol requirements.