tt is a utility designed to help those who host several TeamTalk servers on a single box or virtual machine (VM).
This document describes this utility's usage and capabilities.
This is a command-line utility and is intended for use within a command terminal, such as an ssh session,
Linux console session, or MacOS terminal instance. As such, invocation is typically from a shell
and consists of a command, such as
tt list or
tt rlist -l |more.
This utility is meant to be run on machines where TeamTalk (TT) servers are physically running, or to be run through ssh connections with such machines. This is not a utility of use to TeamTalk users who do not run a server or have direct access to running servers for administrative assistance. It is in fact most likely to be useful to those who run many TeamTalk servers at once. See the "System Requirements" section below for further information.
tt is distributed under the BSD license. Run
tt license for details,
or examine the tt code below the line starting with "
def do_license" to see the license without
running the program.
This Python-based utility was originally inspired by a set of shell and systemd scripts
written and maintained by Daniel Nash (2021-22).
rlist command is a full absorption of a never formally released TTMan project by Doug Lee
started in 2018.
logsum command is a full absorption of a stand-alone utility written by Doug Lee
in 2010 and maintained occasionally since.
In order to function properly, tt requires the following system configuration on the box where it is to be used:
systemdis not fully functional in that environment at this writing. Certain portions of this utility's functionality may work under MacOS, with the same caveat.
python3should run Python version 3.6 or a later Python 3 version.
logcatcommands will be used.
rlistcommand, lsof(8), ps(1), and ideally procfs(5); and sufficient user and/or group permissions to obtain current working directory (cwd) of TeamTalk server processes and contents of TeamTalk server configuration (xml) files.
rlistcommand is one of the few commands that may prove useful on boxes that do not organize their TeamTalk servers as just described. Also, when tt is run through ssh connections, the above requirements apply to the ssh targets more than to the local machine.
Once operational, this utility will also need, or will set up as necessary, the following:
/usr/bin/tt5srv. Note that this will be the file name used, even if the server is a pro server (normally called
ttuser and a
ttgroup, which will own all files and folders under the above folder containing the TeamTalk configuration files. These names can be changed if necessary.
mine, a configuration file
mine.xml, a log file
mine.log(if logging is supported by the server), and a subfolder
files.minefor any uploaded user files. All of these will go under the common folder path for such files, normally
To install and configure this utility on a new system:
/usr/binor another suitable folder that is included in the
PATHenvironment variable for root. This file contains only the
ttfile, without any containing folder.
ttwithout arguments as a command while running as root. This will print a basic help page that includes a list of all available commands, grouped into categories. This is the same page produced by typing
tt helpfollowed by a command or category name will provide more detailed help related to that command or category.
tt.conffile in the same folder where
ttitself resides. This is normally not necessary, however. Run
tt TTConffor details on what can be placed in this file. In summary, this file can alter the following:
tt5srvTeamTalk server binary, normally
tt binupdateas root. If you are managing professional TeamTalk servers, instead run
tt binupdate -p. Add
-bif you want to install a beta TeamTalk server version, or add a version number like 5.11 if you want to select a specific server version. When you do one of these, tt will set up other required infrastructure - systemd files,
ttuser and group, etc., if necessary.
For each new TeamTalk server, run
tt new followed by the exact name to use for the basename
of server files.
tt will, as part of server creation, offer to run the TeamTalk server setup wizard.
To remove a server, run
tt remove followed by the server name.
If you intend that file transfers be allowed by this TeamTalk server, make sure to specify the full path for
the file upload folder and to make the final component of that path take the form of
dot, and the exact server name.
For instance, if all TeamTalk server files are in
/home/tt and the new server is called
/home/tt/files.mine for the user file upload path when prompted by the
TeamTalk server setup wizard.
If you need to reconfigure a server later, use
tt reconfigure followed by the server name.
To make a server start automatically at system boot, run
tt enable followed by the server name.
tt disable will remove this server from the set started automatically at boot time.
A server can be started manually with
tt start and stopped with
tt stop, each
followed by the server name.
A server can also be restarted (stopped and immediately started again) with
tt restart followed
by the server name.
tt reload followed by a server name will reload the server configuration without
restarting the server.
Note that this does not reload everything; run
tt help reload for details.
tt help provides help for all commands supported by the utility.
tt without arguments produces the same information.
This information also includes the revision number of tt itself.
tt help followed by a command name for more help on that command.
This help will often contain more detail than is found in this document.
tt man opens this document from its home on the Internet.
tt rel opens the same document but jumps to the Revision History section (release notes).
Both of these commands accept a
-b option to use the beta tt release's documentation instead of
the regular one.
tt license prints the license that covers the utility.
tt version prints the version of the installed TeamTalk server binary.
tt init will initialize a system for use with this utility but without downloading the TeamTalk
server binary. This command is normally not needed since it is automatically run as part of
binupdate if necessary.
tt list will list servers configured on this box.
See also The RList Command for a way to list actually running servers.
tt log and
tt logcat will print system logs for a server.
These commands require the Linux
See also The LogSum Command for a way to summarize TeamTalk server log files.
This command does not require
tt selfupdate will update this utility in place from its home website.
-b on the command line will update to the latest beta version instead of the latest
If you want to remove this tt utility, use
This will remove as many of the following as necessary and possible, in this order, but will prompt for
permission before removing each in turn:
nwhen prompted. There will be a separate prompt for permission to remove TeamTalk server log files, so you can keep those even if removing all servers.
/home/tt. Note that any "dot files," such as
.bashrc, will be ignored for purposes of detecting an "empty" folder here and will be removed along with the folder if permitted.
ttuser and group if not needed by other files on the box. Note that if these user and group names were changed, they will not be removed.
tt binupdate(which runs
tt5srvTeamTalk server binary.
rlist command can perform the following tasks:
tt rlist [-i | -l] [filters...] [-k | -r]
Without options or with -i, this command lists all servers on the machine that are currently running, in a tabular format. If filters are given, only servers matching all filters are listed. Filters are character strings that may appear in a server's name, config or log file path, or working directory path. A port number may also appear to limit matches to servers running on that TCP or UDP port.
If no formatting options are given, the output consists of the following information for each server listed:
p: Included if this is a pro server (tt5prosrv).
x: The command line for this server is not accessible to tt. When present, this condition invalidates much of the rest of the information provided for this server.
n: Whether this server is running in daemon (d) or non-daemon (n) mode, as determined from its command line.
l: Indicates that this server is keeping a log file. This flag specifically indicates that a log file is being written, and its absence indicates that this is not the case, all regardless of what the configuration file suggests should occur.
v: Indicates that this server is running in verbose mode, printing all log data to its standard output. This flag specifically means that
-verbosewas specified on the command line.
u: Indicates that the UDP port for this server is different than its TCP port. Use
-lto see the UDP port.
-i is given, an extra line is printed for each server indicating the IP addresses
and ports to which clients are connected.
-l is given, the output instead consists of a multiline output block listing fields
of information about the server by field name. The first line for each server appears flush left,
and subsequent lines of information
about that server are indented beneath it.
The first line indicates the server's process id (pid) and full executable path.
Subsequent lines are meant to be self-explanatory, but the following notes may be useful:
Nameis the full server name from the config file, without any abbreviating as discussed above.
Shortis the shortened name as discussed above, when different than
Name. This entry only appears when the name can be shortened.
Flagsare as discussed above but with longer names for clarity.
Clientsincludes IP address and port for each currently connected client.
Local IP Addressis the IP address on this machine that listens for connections to this server. This is normally "*" (meaning any available network can be the source of a connection); but if this server is bound to a specific address/network, it will appear here.
-r is given, each listed server is killed (shut down) or reloaded, respectively,
after the server list is displayed.
help reload for information on what reloading a server does.)
Filters work here just as for the
rlist command without
It is very wise to run a
rlist command without
-r first to make
sure the correct servers will be shut down or reloaded.
This command scans through one or more TeamTalk server log files and produces a summary of contents. This command is based on a 2010 utility that this author wrote before TeamTalk 5 was released and has maintained occasionally since. As a result, this command is capable of understanding both TeamTalk 4 and TeamTalk 5 log files. Support for TeamTalk 4 logs is subject to removal.
Note: Server log inspection is of course only possible for servers that actually write server logs. Additionally, TeamTalk 5.9 introduced the ability for server administrators to alter which events are recorded in such files. Changes in these settings will naturally affect the results of this command. Finally, the specific versions of TeamTalk servers that generated the files will affect what is stored in them; e.g., SSL errors only appear in logs for professional servers, subscription and intercept changes only appear starting in TeamTalk server version 5.11, and log line formats may change from time to time.
Specify one or more file and/or folder names on the command line. Specifying "-" causes stdin to be processed as a TeamTalk server log file. Explicitly named files should be TeamTalk server logs and will be processed. Named folders will be recursively scanned for logs, and each will be processed. Such a scan will consider any file a TeamTalk server log if it meets all of these criteria:
An explicitly listed file may also be a diff output file, in which case only added log lines from any represented actual log file will be examined. In this mode, which is started automatically per file by a recognition of the format, both old-style and unified-style diff files are handled. This also works for "-" to make stdin process as diff output. This in combination with a version control system provides means to get periodic stats from a log file without rotating log files.
Diagnostic output goes to stderr during log processing. The name of each processed file is printed as the file's processing begins. If more than one million lines of data are processed, a line indicating how many million have been processed so far is printed, so that very long-running analyses don't look stalled. (This feature was prompted by a 32 gig, 349 million line analysis run in 2010.) Note that lines are counted across files, not started at one for each file.
At the conclusion of a run, statistics will be sent to stderr indicating number of files and lines processed, number of seconds used, and number of lines processed per second.
Result output is sent to stdout and consists of line categories and counts found of each, after a copy of the final statistics just described that are also sent to stderr.
For each of several line types, the name and number of occurrences is shown. Types with no matches are omitted. Any line not matching a known type will appear in a dynamic category. The category will consist of the line with commonly unique elements replaced, and with a possible prefix indicating things like "no timestamp." "Commonly unique elements" include IP/TCP/UPD addresses, nicknames, etc. This all means that unrecognized lines are grouped sensibly by what they say. Dynamic entries will appear below known types, sorted by decreasing frequency.
WARNING: Although there was much effort to prevent this, dynamic entries may occasionally include IP addresses, channel numbers, etc. They should not include user names, nicknames, channel names, etc. Nevertheless, be sure to scan any results for unwanted information before releasing statistics for public examination.
A few terms in log line type names deserve explanation:
Note: For reasons that will shortly be explained, Many commands are likely not to work as intended when run in this way. Commands especially well-suited to this usage are noted as such later in this section.
tt supports running itself on a remote computer via an ssh connection. The syntax for this is the same as for
local usage except for the addition of a host specification between
tt and the rest of the
command being run.
Running tt in this way is no more or less secure than using scp to copy tt to the remote host and then running
it inside an ssh session remotely; but this single-command approach can definitely be more convenient,
especially for remote hosts that do not also have tt installations.
A host specification may be of the form
user@hostname, as for ssh itself, or
@host if it is not necessary to specify a user name (because of a
entry or because the remote system's user name is the same as the local one).
Note the initial
@ sign that distinguishes a host name from a command word.
It is actually acceptable to include more than one host specification. In that case, each is interpreted in turn from the standpoint of the previous host in the list. The local tt instance is sent to the first host, then run on the first host to send itself to the second, etc., until it is run on the final host to return results all the way back to the local one. The multi-command equivalent to this would be to scp tt to the first host, log into it and scp to the second, etc., then to log in to the final host and run the utility, deleting the various copies afterward. This author expects this scenario to occur infrequently and only to two levels of hosts.
Example commands, each of which list TeamTalk servers on the final host listed in the command:
tt @host1 list
tt @host1 @host2 rlist -l
Note that remote usage of this type causes the local tt to be run on the remote host(s). Hosts need not also have tt installed for this to work.
tt listmay require a remote account with sufficient permissions to read the
/home/ttfolder and its contents.
tt.conffiles present on the local system or any remote system will be ignored. This is because remote tt usage consists of running the local tt code on each host, rather than running any host-specific tt instance.
tt.confwill therefore not be sought in the appropriate location on remote hosts. In practice, this means that an unusual configuration on a much remote host is likely to render remote tt usage impractical against that host.
Especially as a result of the last two items above, the following commands are most likely to be useful when run remotely, some with the given caveats; whereas other commands are likely not to work well remotely:
listif the remote host uses a standard configuration of TeamTalk files.
versionwith the same caveat.
logcat, also with the same caveat.
logsumif given accurate paths to use for finding log files on the remote host.
logsumis the only log inspection command that can work in unusual remote configuration situations. Of course it can only work for servers that actually keep log files and log wanted event types.
help, but of course only in the trivial way of verifying that a remote host is capable of running the utility; e.g., that its default version of
Issues shown in this section may be fixed in future tt revisions but are not addressed as of this writing.
tt help log does not work.
rlist command may show 0 connections to all servers if the user id under which it is run does
not have sufficient permissions to see sufficient information from lsof.
This situation does not produce an error message.
The requirements and operation of the
rlist command is notably different from other commands,
which may confuse new tt users.
Short answer: I wrote it for myself and a few friends, then decided to publicize the result. The rest of this section is for anyone more curious and includes more information about Daniel Nash's original shell script and this author (Doug)'s 2018 TTMan program, on both of which this Python utility is based.
When I began my excursions into TeamTalk in 2011 or so, there were comparatively few people setting up their own servers. By now (2022), this has changed significantly as more and more people have begun experimenting with Linux variants, both in the cloud and on home equipment. Now there are not only many people running their own servers but also a fair number of people running TeamTalk servers for others, sometimes for free and sometimes for nominal fees.
One of my trademarks is liking to automate just about anything that is a sufficient mix of annoying and repetitive. As I have often helped people with Linux, TeamTalk server setup and administration, and the like; I wound up helping several people at once in 2021 and 2022 with the administration of what I started to call "TeamTalk server farms," meaning boxes or virtual machines that hosted a sometimes significant number of individual TeamTalk servers. I had already been doing this for one person for years and had, starting in 2018, written the TTMan utility for listing information about running servers on a box.
In 2021, I became aware of Daniel Nash's shell script that sought to ease the management of such multi-server boxes. I considered the idea quite useful but found it hard to implement sufficient error checking strictly within shell scripting. Versions of Daniel's work also varied from machine to machine; and some used zsh while others used Bash. This complicated sharing updates.
I thus started working on a parallel Python version and told him so, showing him code now and then as the project progressed. Many commands in this Python-based tt utility first appeared in Daniel's shell script. Daniel is also the author of the systemd service file that is included within this Python utility. For reference, I have saved a June 2, 2022 copy of Daniel's distribution on my site. This was the latest version of his work that I referenced while writing this utility.
At the time of writing for this section (September, 2022), I am using this utility to help manage approximately 25 boxes that each run several TeamTalk servers; and I thought I might share the utility for anyone else out there doing a similar thing.
Here is the revision history of this utility, most recent revision first:
binupdatecommand accepts a TeamTalk version number, like 5.11, to force downloads to come directly from a specific folder of binary download files on the TeamTalk website. This feature is a workaround for occasions when a binary download for an old Linux version is available but not advertised on the TeamTalk site's download pages. It is also a way to revert to an older TeamTalk server version. Example usage:
tt binupdate 5.11
binupdatewill fail gracefully if the newly downloaded server will not run. This was prompted by a brief moment during which the TeamTalk 5.11 release for Ubuntu 18 was not available and several box administrators tried to install the Ubuntu 22 version instead, with troublesome results.
rlistcommand, to limit output to servers running on a specific TCP or UDP port.
tt binupdatebetter handles new installs into non
/usr/binfolders without running as root. Such a setup constitutes an unusual
tt help, and first published release outside of a circle of friends. There were four releases among friends before this one, dating back as far as July 5, 2022; and I had handed out copies of TTMan a few times individually as well.