tt is a utility designed to help those who host several TeamTalk servers on a single box or virtual machine (VM). It may also be used to facilitate testing of TeamTalk server versions and configurations in a local Windows/WSL or virtual-machine environment, though not all features may be supported there. 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
or a Linux or WSL console session. 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
The Windows Subsystem for Linux (WSL) does not, at least by default, support use of the
utility for managing services and startup-time activities.
The use of tt under WSL will therefore likely be limited to
TeamTalk server binary installation and updating,
and TeamTalk server creation and configuration.
The starting and stopping of TeamTalk servers must be managed in some other way.
If systemd is enabled under WSL, other features of this utility should begin to function as expected.
There are numerous limitations to this utility's ability to function effectively on MacOS:
sudo ln -s /Applications/TeamTalk5.app/Contents/Server/tt5srv /usr/bin/tt5srv
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 many commands
tt list will list servers configured on this box.
See also The RList Command for a way to list actually running servers.
tt analyze analyzes the server configurations on this box and reports any of the following as
For each of IPV4 and IPV6 bindings, TeamTalk can be bound to a specific IP address or to all IP addresses. At
first glance, it may seem simple to have this utility determine whether two servers' port bindings actually
collide, by comparing all of their IP address bindings to look for overlaps (same address, both specifying
all, or one specifying all).
However, at the operating system level, it is possible for a server to answer IPV4 requests on an IPV6
interface. This means that one server binding to the address
126.96.36.199 and another server binding
:: which means all IPV6 addresses, may and may not collide depending on how that server's
operating system is handing IPV4 requests.
This utility therefore does not attempt to report whether two bindings overlap, so that it won't mislead
anyone by mistake.
tt listcommand; i.e., all servers defined on the box. As an alternative, file and/or folder names may be specified on the command line, in which case they are scanned instead. Folders appearing on the command line are searched recursively Files whose names do not end in
.xmland folders whose names begin with a dot are quietly skipped.
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
-y will force the update without a prompt for permission.
-n will instead just check for an update and report the situation
without actually updating the utility.
-y is given along with
-n, it will be ignored and no update
will be performed.
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 init(which may be run as needed by many commands).
tt5srvTeamTalk server binary.
rlist command can perform the following tasks:
tt rlist [-i | -l] [-<count>[d|i|t]] [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.
The list can also be filtered with an option consisting of a dash (-), a number 0 or
higher, and optionally a letter indicating which count to check.
Counts are i for IP count, d for duplicate count, and t (the default type if
none is given) for total of the two.
A common option here is
-1 to ignore all servers with only one active connection, which
effectively causes servers to be ignored if they currently don't have enough tonnections to permit an active
-0 is also useful for removing servers from the list that have no connections at all.
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.
.xmlextension. When config and log paths differ or the server's working directory is not where its files reside, this path will still reflect the location of the server's configuration file.
-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.
Regardless of output format, the output ends with a single line that indicates the following:
-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:
For box administrators who allow TeamTalk users to upload files to TeamTalk servers,
fln command may save significant disk space depending on user upload patterns.
This command will look for duplicate files among all files uploaded to all TeamTalk servers managed by this
utility and can convert sets of duplicates into links to a single instance of the file.
If run without option arguments,
fln will first report what can be done.
The output consists of statistical information on what was found, as well as
the specific names of files to be linked.
This may cause significant output on the first
tt fln run on a particular box.
tt will then prompt the user for permission to make the suggested links.
The above behavior can be altered with any one of the following options:
tt fln also accepts one or more folder paths on the command line.
By default, the target box's TeamTalk file tree (
/home/tt unless altered by
If one or more folders are given,
tt fln scans the listed folders instead.
This is useful for boxes that do not use the normally expected file structure for their TeamTalk server data.
tt fln -q is a decent candidate for a cron job to be run as the TeamTalk server user
There probably won't be a need to run this very often though, unless TeamTalk users are in the habit
of uploading unusually often and duplicating many of their downloads across servers and channels..
Important notes and caveats:
-b) however, linking can be undone by moving all ".bk" files over the links that replaced them, without that extra extension. Again though, since this negates all space savings until the backup files are removed, this is not expected to be a common practice.
tt flnonly considers linking files whose names follow the TeamTalk naming pattern for user uploads (
data_*.dat), scanning a large area with this command is not expected to cause any significant surprises, other than taking too long if scanning a far larger disk area than necessary. However, storing server data backups in subfolders scanned alongside the live data folders could result in unwanted hard links between live and backup data files.
rsyncto back up TeamTalk server data, including uploaded files: If you use
fln, you might also include
rsynccommands, to check for hard links. Failure to do this will require
tt flnto be run on the backup site as well, or the backup will contain duplicates that are not linked to save space.
-bflag to keep backups of newly made links, failure to remove these before a
rsyncbackup may also increase the backup footprint substantially, especially if
rsyncis not looking for hard links.
ln is the name of the Linux (and other flavors) command for making hard file links.
The letters "fln" do not in fact stand for "file links, now!" although given the distinct possibility
tt fln -y being used often enough to rescue a file system with no remaining disk
space, this tt author is happy to let people think so.
One final very fine bit of print on how
tt fln determines how to link files:
If a user upload exists in five places (channels and/or TeamTalk servers on the same box), one
instance must be selected as the one to which all others will point.
This will be called the target instance.
The following rules apply, in order:
tt flnwill warn of such external links on finding them. If two different instances of the same user upload have external links,
tt flnwill also indicate this as "held space," meaning space that is held by external links despite
tt fln's efforts.
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.
StrictHostKeyChecking=nois set, so that any new or changed host fingerprints result in local additions to the
known_hostsfile without a user prompt. Any modifications to this file will, however, cause a standard warning to be printed.
BatchMode=yesis also set. This causes any password prompts to be avoided and connections to servers requiring them to fail. This will print a failure notice for the user.
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:
flnif 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:
tt newcommand for creating a new server, the incomplete configuration file created by the TeamTalk wizard will be removed. The Ctrl+C keystroke previously terminated not only the
tt5srvwizard but also the tt utility itself.
tt reconfigurecommand will still allow a choice on how to handle any changes made to the server, rather than aborting the tt utility along with the wizard.
tt reconfigurecommand's final prompt, asking how to handle the server update, includes a third, "Delay" choice for letting changes take effect on the next server restart rather than forcing them to take effect immediately. There is also no prompt at all if the configuration file was not changed.
detailstag that may be expanded to show them. Among the benefits of this, heading count is reduced and text searches won't match very old material.
tt rlistincludes, in the final path on each tabular line, the basename of the server's configuration file.
tt analyzecommand that reports possible problems among servers on a box.
-coptions have been added, the last two being equivalent to one another.
binupdatecommand is fixed to allow three-part version numbers like 5.13.1 in addition to two-part ones like 5.13. This was inspired by many Ubuntu installations requiring a 5.13.1 update that was not officially published on the TeamTalk site but that was nevertheless available (May, 2023).
tt rlistincludes total connection count information that can help in determining how many users are connected to TeamTalk servers and how many connections might be text clients rather than active voice connections.
rlistcommand also supports a filter by connection count syntax, most useful for eliminating from the output any server with no active connections (
-0) or no active possible conversations (
tt init. Many commands do this if necessary, but
tt binupdateis not one of them.
tt help logand
tt help relwork as intended.
tt rlist -kworks without a filter rather than being ignored. (This bug was caused by a block of four code lines being indented one too many levels.) Note though that this is not a recommended way to shut down TeamTalk servers that are managed by this utility, because any server controlled by
systemdwill just restart.
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.