tin (Usenet client)

authors:

~ant


table of contents

tin is a text-mode threading NNTP and spool-based Usenet client for a variety of platforms.

We start with configuring a connection in tin. That done and tin having started without errors, jump over to Interface overview lest you become lost and bewildered in its apparently unwelcoming blank screen of emptiness, which only seems that way to the uninitiated.

Local connection §

tin is installed on tilde.club and preconfigured to access the local spool of the news.tilde.club server by default. You need only run tin without arguments:

$ tin

There is also a local NNTP port on the tilde.club premises, to which you can connect via:

$ tin -r [-g localhost[:119]]

-r stands for remote, and rtin acts as an alias to tin -r. -g specifies a server or its alias, overriding the default, and implies -r.

Remote connection §

Server configuration §

To connect tin to a remote news server over NNTP, a little bit of setup is required. By default, most of your tin configuration is located in the .tin directory in your home. In order to register a remote server, add a line to the newsrctable file in that directory, with the following whitespace-separated fields:

  1. server address with an optional port after a colon, which is needed only for non-standard ports,

  2. path to the newsrc file for that server, for internal use by tin to store an index of downloaded articles. for each newsgroup.

  3. optionally–but highly recommended—a short alias for the server, to facilitate invocation of tin.

For example, here are a few lines from my newsrctable:

news.tilde.club             ~/.tin/newsrc.club     tc
news.eternal-september.org  ~/.tin/newsrc.e-s      es
fidonews.mine.nu            ~/.tin/newsrc.mine.nu  fi
news.gmane.io               ~/.tin/newsrc.gmane    gm
*                           ~/.tin/newsrc.local

Now you can connect to any of the registered servers via tin -g. For example, to read the tilde.club server configured above, enter:

$ tin -g tc

But you will not be able to post yet if the server requires authentication, as most servers do:

Authentication §

tin reads your credentials for each server from the file .newsauth, by default located in your home directory. It also has a table structure similar to that of newsrctable, with one line per server. This time, the fields are:

  1. server address,
  2. password,
  3. username.

For example, my line for the tilde.club server (with a fake password, however) is:

news.tilde.club  ant  H1dd3nPa$$w0rd

Some servers (Eternal September being one of them) require that the client authenticate immediately upon connect, or they will not show you all newsgroups, if any. To cause tin to authenticate early, pass the -A option, e.g:

tin -Ag es

If you are among the unlucky fellows who are guilty of using a password with space or (we are embarrassed to say) tab characters, you will need to enclose it in double quotes ("). Make sure your .newsauth is not readable by other users:

$ ls -ld    ~/.newsauth # view permissions
$ chmod 600 ~/.newsauth # set  permissions

Specifying the NNTPS protocol §

By default, tin connects over the unencrypted NNTP protocol. These days, however, most servers support the more secure NNTPS. To cause tin to use it, it should be invoked with the -T option. So, the final invocation for Eternal September, with the necessary initial authorisation and the recommended encrypted connection, is:

$ tin -ATg es

Persisting server-specific commandline parameters §

To save the remembering whether -T and -A are required for a server and typing them at every invocation, these options can be indicated in the server-specific configuration file serverrc, the default full path to which is:

~/.tin/<server>/serverrc

where <server> is the news server hostname (as specified in newsrctable). The add_cmd_line_opts parameter in that file specifies additional commandline options that tin is to assume while connecting to that server. For example, to set -A and -T for Eternal September, I added the following line:

add_cmd_line_opts=-AT

to my ~/.tin/news.eternal-september.org/serverrc .

Now I can connect with just:

$ tin -g es

See tin(5) for a list parameters supported in that configuration option.

Interface overview §

Built-in help §

When tin starts for what it thinks is the first time, it shows an introductory help screen, which you are advised to peruse. If you skipped it, press q to quit tin, delete your ~/.tin directory, (or rename it if it already contains your customisations, to reinstate it later) and start tin again.

After the intro, you end up in the main interface, where context-sensitive help is available in two forms:

  1. as a brief on-screen summary of most important keys, toggled by H and shown by default, and
  2. as a more (but not quite) complete full-screen command reference invoked by h and sporting its own keys summary (H) for navigation.

Basic operation §

tin works at four nested levels with (more or less :-) uniform navigation within and between them:

Level Operates on Symbol
selection newsgroups S
group threads G
thread articles T
article single article A

tin starts at the topmost level (selection), showing a list of subscribed newsgroups. If you are running it for the first time, the list will be empty. Press y to yank in the available newsgroups, then subscribe to the desired ones, by selecting a group with either of j/k for up/down, [0-9]+ for group number, or / for textual search, and subscribing to it with s. Press y again to see only subscribed groups.

Whereas the selection, group, and article levels are linked with fixed up/down transitions, the thread level is the odd one out, for it comes between the group and article levels only upon explicit invocation from either of them by the l key. Furthermore, if the article level was entered from the thread level the level-up command (q) goes back to the thread level instead of the group level.

The levels share many common keys for navigation and operations, often borrowed from The Vi editor interface. The most important keys are:

Key Level Action
H SGTA toggle panel with brief help
h SGTA view full-screen help
j,k SGTA next/prev. group/thread/article/line
[1-9]+ SGR highlight by entry number
Return SGT level-down (into highlighted element)
q SGTA level-up, or quit
l GA open thread view, mem. as list of articles
/ SGTA search forward
? SGTA search backwards
y S toggle display of all/subscribed groups
s,u S subscribe/unsubscribe to/from selected group
r SG switch between read/all
TAB,n S into next unread group
TAB GTA open next unread article
N,P GA open prev/next unread article
n,p GA open next/prev article
N S select next unread group
w G write a new post
f A follow-up (reply)
c,C SGTA catch-up (mark read) group (SG) or thread (TA) and move to the (c:next, C:next unread) one
K GTA mark current thread (G) or article (TA) as read and move to the next unread one
z SGA mark group/base article/article unread
Z TA mark thread unread
Y S load new posts from the server (if any)
M SGTA open the menu

Solutions to typical problems §

Posting fails for lack of an FQDN §

Well, do get yourself an FQDN, becoming a first-class netizen. While you are busy acquiring a domain, obtaining a static IP from your ISP, building yourself a server, and configuring an authoritative domain-name server on it, set your $HOSTNAME environment variable to a value resembling an FQDN, by adding some such statement as

export HOSTNAME=invalid.domain

to your interactive shell’s init script (~/.profile, ~/bash_profile, &c) as a temporary solution1.

If such mockery is below your standards or otherwise offends your taste, add the line disable_sender=ON to the /etc/tin.defaults file. You will need root access to do that. If you don’t have it, ask your BOFH systems administrator to do it for you.

Tin takes too long to start §

Try starting it with the -Q option.

See also §

tin(1) for a UI reference and tin(5) for a configuration reference.

Credits §

The following people have helped improve the article:

Debits §

  • Shall I describe the common prefixes on
    • groups,
    • threads, and
    • articles,
    or merely direct the reader to the manual?
  • arrange the principal keys in the way most convenient to the learner:
    • with grouping by relative function
    • with ordering by decreasing importance.
    • abridge that list, leaving out the less important ones?

Questions and improvement proposals are welcome at the author’s @tilde.club e-mail.

  1. There is nothing more permanent than the temporary.↩︎