rcon

README

rcon

A RCON client for executing commands on a remote RCON server.

This Go-based RCON client allows Minecraft server administrators to send commands to their server over a remote RCON connection. With this client, you can easily send commands and view output on the console without having to log in directly to the server.

This client implements the RCON protocol used by Minecraft servers and has the potential to work with other game servers as well, though it hasn't been extensively tested with them.

To use the client, you will need to have access to the server's RCON password and IP address/hostname. Once connected, you can send commands through the client's terminal interface and receive output on the console like you would with the standard Minecraft server console.

Installation

Prebuild

Download the latest build for your platform from the latest release

Build

You can also build your own executable. This requires:

git
go v1.18 or higher
make

Run these commands to build the executable:

git clone https://github.com/Sch8ill/rcon
make -C rcon
mv rcon/build/rcon-cli rcon-cli
rm -rf rcon

Usage

CLI

USAGE:
   rcon [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --address value, -a value   address of the server you want to connect to (localhost:25575 for example) (default: "localhost")
   --password value, -p value  password of the RCON server you want to connect to (default: "minecraft")
   --command value, -c value   a single command to be executed
   --timeout value, -t value   timeout for the connection to the server (default: 7s)
   --no-colors, --no-colours   if the cli should not output colors (default: false)
   --help, -h                  show help
   --version, -v               print the version

Example commands

Move into the directory of the executable and open up a terminal.

Open up an interactive RCON terminal:

./rcon-cli -a <the-servers-address> -p <the-servers-password>

Run a single command on the server:

./rcon-cli -a <the-servers-address> -p <the-servers-password> -c <the-command-that-shall-be-executed>

Take a look at the other command flags for more features.

Environment Variables

Instead of specifying command line options each time, you can also use environment variables to set the default values. Environment variables are automatically checked and used if available. Environment variables take precedence over the default values.

Available environment variables:

DEFAULT_RCON_ADDRESS: Address of the server you want to connect to. DEFAULT_RCON_PASSWORD: Password of the RCON server you want to connect to. DEFAULT_RCON_TIMEOUT: Default timeout for the connection to the server. Example:

export DEFAULT_RCON_ADDRESS="my-server:25575"
export DEFAULT_RCON_PASSWORD="my-password"
export DEFAULT_RCON_TIMEOUT="10s"

Libary usage

Install the module using:

go get github.com/sch8ill/rcon

Import it:

import "github.com/sch8ill/rcon"

Create a new RCON client:

client, err := rcon.Dial("localhost", "password", 5) // address, password, timeout
if err != nil {
  panic(err)
}

Execute a command over RCON:

output, err := client.ExecuteCmd("some-command")
if err != nil {
  panic(err)
}

fmt.Println(output)

Documentation

Index

• Constants
• type ConnectionState
• type Packet
  • func (p *Packet) Bytes() []byte
• type RconClient
  • func Dial(addr string, password string, timeout time.Duration) (*RconClient, error)
  • func NewClient(addr string, password string, timeout time.Duration) *RconClient
  • func (rc *RconClient) Authenticate() error
  • func (rc *RconClient) Close()
  • func (rc *RconClient) Connect() error
  • func (rc *RconClient) ExecuteCmd(cmd string) (string, error)

Constants

const (
	SERVERDATA_AUTH           int32 = 3
	SERVERDATA_AUTH_RESPONSE  int32 = 2
	SERVERDATA_EXECCOMMAND    int32 = 2
	SERVERDATA_RESPONSE_VALUE int32 = 0

	HEADER_SIZE     int = 4
	MIN_PACKET_SIZE int = 10
)

Types

type ConnectionState

type ConnectionState int

const (
	Connected ConnectionState = iota
	Disconnected
	Authenticated
)

an "enum" that represents the current connection state

type Packet

type Packet struct {
	ID   int32
	Type int32
	Body []byte
}

func (*Packet) Bytes

func (p *Packet) Bytes() []byte

type RconClient

type RconClient struct {
	Address   string
	Password  string
	Timeout   time.Duration
	Conn      net.Conn
	ConnState ConnectionState
}

func Dial

func Dial(addr string, password string, timeout time.Duration) (*RconClient, error)

creates a RCON client and establishes a connection

func NewClient

func NewClient(addr string, password string, timeout time.Duration) *RconClient

creates a new RCON client

func (*RconClient) Authenticate

func (rc *RconClient) Authenticate() error

authenticates the client using the clients password

func (*RconClient) Close

func (rc *RconClient) Close()

"closes" the RCON client by terminating the underlying TCP connection and setting the clients connection state to disconnected

func (*RconClient) Connect

func (rc *RconClient) Connect() error

establishes the underlying TCP connenction of the RCON client

func (*RconClient) ExecuteCmd

func (rc *RconClient) ExecuteCmd(cmd string) (string, error)

executes a command on the remote server