Introduction
In recent years we’ve seen an increasing rate of customer requests for a command-line alternative to the ThinLinc web administration interface. As a response to this uptick, ThinLinc 4.15.0 brings the new command-line administration tool tlctl. Based on the feature requests we’ve gotten over the years, by far the most popular request was simplifying administration of running graphical sessions in large ThinLinc clusters.
Administration of the sessions in a ThinLinc cluster has, up until now, exclusively been done through the web administration interface. In smaller ThinLinc clusters, that way of session management is quick and easy. However, it becomes inefficient when the user count gets large. Unlike the web administration interface, tlctl allows both filtering of sessions and terminating multiple sessions simultaneously – instrumental when managing large clusters.
Listing sessions
Just as the web administration interface, tlctl is to be run on one of the master nodes. Firstly, tlctl lets you see all currently running sessions:
$ sudo tlctl session list USER DISPLAY AGENT STATUS AGE ================================================================ robert 10 agent1.example.com disconnected 6 day(s) samuel 10 agent2.example.com connected 9 hour(s) william 12 agent1.example.com connected 30 minute(s) Listed 3 session(s).
The information presented in this example is identical to what’s visible in the web administration session list. However, tlctl also allows filtering this list. For example, it is possible to only list and count the sessions running on a specific agent, or belonging to a specific user:
$ sudo tlctl session list --agent=agent1.example.com USER DISPLAY AGENT STATUS AGE ================================================================ robert 10 agent1.example.com disconnected 6 day(s) william 12 agent1.example.com connected 30 minute(s) Listed 2 session(s). $ sudo tlctl session list --user=samuel USER DISPLAY AGENT STATUS AGE ========================================================== samuel 10 agent2.example.com connected 9 hour(s) Listed 1 session(s).
These filtering arguments can also be combined. To uniquely identify a single session, you can filter on display and agent:
$ sudo tlctl session list --agent=agent1.example.com --display=12 USER DISPLAY AGENT STATUS AGE ============================================================= william 12 agent1.example.com connected 30 minute(s) Listed 1 session(s).
Terminating sessions
As briefly mentioned in the introduction, tlctl is also capable of terminating sessions using the tlctl session terminate command. The terminate subcommand employs the same filtering options as tlctl session list with the difference that --all has to be explicitly specified to terminate all sessions. For example, to terminate any sessions belonging to the user william:
$ sudo tlctl session terminate --user=william Refreshing session information... Terminating: USER DISPLAY AGENT ==================================== william 12 agent1.example.com Summary: Terminate 1 session(s) Is this ok? [y/N]: y
When running tlctl session list, you may come across sessions marked as unreachable:
$ sudo tlctl session list --agent=dead-agent.example.com USER DISPLAY AGENT STATUS AGE ============================================================= anton 10 dead-agent.example.com unreachable 6 day(s) eric 11 dead-agent.example.com unreachable 8 day(s) jens 13 dead-agent.example.com unreachable 8 day(s) Listed 3 session(s).
This means the sessions in question reside on an agent node that cannot be reached by the master node. Naturally, such sessions cannot be terminated. However – we can make the master node stop tracking them. Abandoning thus risks leaving stray processes on the agent that will stay alive until the next system restart. Given an agent node that won’t come online again though, this is the right thing to do. The --allow-abandon flag is used to abandon unreachable sessions:
$ sudo tlctl session terminate --allow-abandon --agent=dead-agent.example.com Refreshing session information... Abandoning: USER DISPLAY AGENT ====================================== anton 11 dead-agent.example.com eric 13 dead-agent.example.com jens 10 dead-agent.example.com Summary: Terminate 0 session(s) Abandon 3 session(s) Is this ok? [y/N]: y 3 session(s) are about to be abandoned. This may leave stray processes. Do you really want to abandon these? [y/N]: y
If this is not done, the ThinLinc client would ask all of the users with unreachable sessions whether they want to abandon the sessions or not the next time they reconnect. Hence, if you’re certain that the agent node won’t come back online, abandoning the sessions for the impacted users may avoid some unnecessary confusion.
Conclusion
This small demonstration does not cover all of what tlctl has to offer. We urge you to check out the tlctl(8) and tlctl-session(8) manual pages for the full documentation.
We thank our community for their continuous feedback and support, which has been instrumental in shaping this tool. We look forward to hearing your opinions on how we can refine tlctl and what features you want to see going forward. Thank you for being a part of this journey with us. Happy administrating!