Manual

The server waits for incoming connections and spawns a new thread for each client.

Each process runs in its own thread, too.

Protocol

Every command you send to the server returns a status:

  • OK

  • OFFLINE process(es) do(es) not exist

  • EXISTS (returned by start) a process with this name is already running

  • UNKNOWN unknown error

  • PERMISSION_DENIED requested action needs other/higher privileges

  • ERROR protocol error

  • AUTHENTICATION_REQUIRED waiting for credentials

  • AUTHENTICATION_ERROR authentication failed (E.g. wrong credentials)

If a command returns additional information, it is prepended. E.g. list and cat return an additional part after the status.

The regex:-lines below show protocol syntax. (Tip: \d{2} means 2 numbers)

Syntax

All parts are prefixed by their length!

E.g. The first part of each line, the command, is prefixed by 2 digits:

  • 05start…

  • 07command…

  • 03cat…

The regex: would be \d{2}command (following the arguments).

Authentication

When a client connects it needs to authenticate first! Available authentication methods depend on whether your using a tcp socket or a unix domain socket.

username and password are both prefixed by 2 numbers.

regex: \d{2}username\d{2}password

All processes are executed as the configured user. You can configure a default user and/or specific ones for each virtual-user

TCP socket

E.g. tcprocd -H localhost -P 20103 or just tcprocd

When connecting, the server will always respond with AUTHENTICATION_REQUIRED and wait for credentials.

regex: \d{2}username\d{2}password

E.g.:

06knoppo21myultrasecretpassword

SECURITY RISK: Not configuring a user and group results in the processes being executed as root if tcprocd itself is run as root!

Unix domain socket

E.g. tcprocd -s /var/run/tcprocd.socket

The username will be the connected local user.

All processes are executed as the connected user by default. (Instead of the configured tcprocd default user!) This can still be changed at the user level.

When connecting to the server (E.g. tcproc -s /var/run/tcprocd.socket) it will either respond with OK or AUTHENTICATION_REQUIRED.

The password is optional for unix domain socket connections! If a user has a password the server will ask for it by returning AUTHENTICATION_REQUIRED. (Send only the password!)

regex: \d{2}password

E.g.:

21myultrasecretpassword

Commands

list

regex: 04list

(no arguments)

List running processes of the connected user. One item per line.

The list will contain all processes if the connected user is an admin.

start

regex: 05start\d{2}process\d{3}command\d{3}path

Start a new named process. The path to run the command in is optional (just pass 000).

E.g. Run java -jar minecraft_server.1.8.jar -server nogui as myserver in /home/minecraft/myserver/:

05start08myserver048java -jar minecraft_server.1.8.jar -server nogui024/home/minecraft/myserver

kill

regex: 04kill\d{2}process

Kill the given process if it is running.

E.g.:

04kill08myserver

cat

regex: 03cat\d{2}process\d{1}start_line

Return lines of stdout starting at start_line and one item per line.

Pass 0 to get everything since the process started.

E.g.:

03cat08myserver10

03cat08myserver42723

This might look confusing. Keep in mind that the start_line is prefixed by a single number:

  • ‘0’ is 1 number so its prefixed by ‘1’ -> ‘10’

  • ‘2723’ has 4 numbers so its prefixed by ‘4’ -> ‘42723’

command

regex: 07command\d{2}process\d{3}command

Send a command to stdin.

E.g. kick r4lph from the server:

07command08myserver011kick r4lph

attach

regex: 06attach\d{2}process

Attach to the given process.

E.g.:

06attach08myserver

As soon as the server responds with OK the connection will be line-based until it is closed! Every line you send will be written to the attached process’s stdin.