Logo gARIM Messaging Program v0.3 Help Logo

Introduction

ARIM means "Amateur Radio Instant Messaging" and the gARIM program is a GUI host mode program for the ARDOP TNC being developed by Rick KN6KB and John G8BPQ.

gARIM is written in C and C++, distributed as source code under the terms of the GPL 3.0 license. Developed on Ubuntu Linux, it should compile and run on any modern Linux installation (including Raspbian for Raspberry Pi). Compiling the source code is easy, the only build dependency beyond the standard C libraries are the fltk and zlib development libraries.

Features include:

The gARIM program is a work in progress and I am interested in feedback. I monitor the ARDOP Users group at groups.io and can be reached there, or at the arim-ham Yahoo group where files and other information will be posted.

The gARIM screen layout Color coding scheme Downloading and installing
Configuration Rig Control/PTT Attaching to a TNC
View Quick Help View Recent messages View Ping History
View Connection History Change the Calls Heard timestamp format Clear the new message and file counters
Press <ESC> to abort send or receive Using the command line Sending commands to the TNC
Viewing and changing TNC settings Composing a message (to outbox) Pinging another station
Using Pilot Pings ARQ: Connecting to a remote station ARQ: Sending queries to the remote station
ARQ: Sending messages to the remote station ARQ: Downloading messages from the remote station ARQ: Listing shared files on the remote station
ARQ: Reading files from the remote station ARQ: Downloading files from the remote station ARQ: Uploading files to the remote station
ARQ: Session authentication ARQ: File access control ARQ: Password management
FEC: Sending an unproto message FEC: Sending a message (to TNC) FEC: Working with the message inbox
FEC: Working with the message outbox FEC: Working with sent messages FEC: Querying another station for information
FEC: Retrieving files from another station FEC: Using message send repeats FEC: Beaconing
RF channel busy detect Working with the local shared files viewer Viewing and editing files
Serving dynamic files Logging  

The gARIM screen layout

The gARIM screen is divided into different sections. Some of these can host more than one "view". The current view is identified by the title at the bottom of these sections.

gARIM

gARIM

Color coding scheme

The Traffic Monitor and TNC Command Monitor views show very different types of information so different color coding schemes are used for each. The Calls Heard view is just a reflection of information in the Traffic Monitor view and uses the same color coding conventions.

Downloading and installing

The prerequisite for gARIM is the ARDOP TNC. Both version 1 and version 2 TNCs may be used. Three versions are available for each: ardop2 for Linux, piardop2 for the Raspbian OS on RPi, and ARDOP_2Win for Microsoft Windows.

Information about downloading and installing the ARDOP TNCs is found here:

Next, you need to either build gARIM from source or download a "portable" precompiled binary package.

Run garim with the --help option to print out command line options:

Usage: garim [OPTION]
  -v, --version            print version information
  -f, --config-file FILE   use configuration file FILE
  -p, --print-conf FILE    print configuration file listing to FILE
  -h, --help               print this option help message

Configuration

By default, gARIM reads an "ini" format configuration file named garim.ini at startup. If you are using the portable binary gARIM distribution, this file is located in the same garim-0.3 directory containing the gARIM executable file and data files. If you compiled and installed gARIM from the source distribution, this file is located in the garim data directory in your home directory. To override the default configuration file location, run arim with the --config-file command line option, for example:

garim --config-file /home/nw8l/HF/garim-net.ini

To open the configuration file, choose File->View or Edit Config File... from the main menu:

gARIM

If you make changes, press Save to save them, or Cancel to abandon them. Saved changes won't take effect until gARIM is restarted.

Multiple TNCs can be defined. A subset of the ARDOP TNC parameters are initialized here, but these can be overridden from the TNC command line after the program starts. Most options have reasonable default values which are used if they are not found in the configuration file.

To print the configuration file parameters to a file for analysis, run gARIM with the -p option. For example:

arim -p dump.txt

In the file is a listing of the parameters and their values after processing, which can be helpful for troubleshooting. Any invalid parameter values will be replaced with default values, and parameters with misspelled names will be absent.

Rig Control/PTT

The gARIM program has no rig control features! It depends on the rig control features embedded in the ARDOP TNC.

I use VOX on my rig and it seems that Signalink cards work too. In both cases the VOX hold or SignaLink DLY must be set to minimum.

Attaching to a TNC

Make sure the ARDOP TNC is running. Choose TNC->Attach from the main menu and select a TNC:

gARIM

The TCP connection will be made and initialization commands from the program to the TNC will scroll by in the TNC Command Monitor. The TNC Status Line will display the number and name of the attached TNC.

To detach from the TNC, choose TNC->Detach from the main menu.

If you prefer to use the keyboard, press <SP> to open the command prompt. To attach, enter the att n command where n is the TNC number. To detach, enter the det command.

View Quick Help

Choose Help->Quick Help... from the main menu:

gARIM

Here are a listing of hot keys and commands, a key to FEC and ARQ mode status bar indicators, and a listing of ARIM/ARDOP frame types. Press Done to quit.

View Recent messages

Select the Recents tab:

gARIM

This is a listing of headers for messages recently received. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

To read a message, right-click its header line and choose Read... from the pop-up menu:

gARIM

This opens the message viewer.

gARIM

Press Done to quit. Shortcut: double-click a header line to read the message.

To save a message to a disk file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

gARIM

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

When connected to a TNC, you can forward a message in the Recents view to another station. Right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

gARIM

Enter the call sign of the destination station and press OK to forward the message. The Use compression option is only available in ARQ mode. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

To clear the Recents view, choose Edit->Clear->Recents from the main menu.

View Ping History

Select the Ping History tab:

gARIM

Here is a listing of signal reports resulting from ARDOP pings sent to other stations by the TNC or from pings sent to the TNC by other stations. The history shows a line for each remote station, sorted in reverse chronological order (most recent on top). Each line includes, from left to right:

Press <CTRL-T> to toggle the timestamp format between elapsed time or the clock time.

To clear the view, choose Edit->Clear->Ping History from the main menu.

View Connection History

Select the Connect History tab:

gARIM

Here is a listing of connection reports resulting from both inbound and outbound ARQ connection requests. The history shows a line for each connection, sorted in reverse chronological order (most recent on top). Each line includes, from left to right:

To clear the view, choose Edit->Clear->Connect History from the main menu.

Change the Calls Heard timestamp format

Choose View->Calls Heard from the main menu and select an option from the fly-out menu:

This affects the timestamps shown in the Calls Heard list and Ping History view.

Shortcut: Press <CTRL-T> to toggle the timestamp format.

Clear the new message and file counters

Choose View->Clear->New Msg and File Counters from the main menu. This clears both counters, which are located at the end of the TNC Status Line.

gARIM

The counters increment when a new message or file is received. They are helpful as indicators of activity during periods of unattended operation. Note that files received in FEC mode are encapsulated in a message or query response frame, so the message counter is incremented, not the file counter. New messages are listed in the convenient Recent Messages view. New message and file counter values are lost when the program is closed.

Shortcut: Press <CTRL-N> to clear the new message and file counters.

Press <ESC> to abort send or receive

Sometimes it's necessary to abort a transmission in progress or halt a receive operation instead of waiting for it to time out. To do this press the <ESC> key to cancel the operation and return gARIM to the idle state. When transmitting, this makes the TNC stop sending, flushes the transmit buffer, and cancels any pending message repeats. When receiving (or waiting for) an ARIM frame the time out counters are reset and any pending response is canceled, making the TNC available for a new send operation immediately. A confirmation message will appear briefly on the Status Bar and the Busy/Idle indicator will reflect the change.

In FEC mode, pressing the <ESC> key also resets the [RF CHANNEL BUSY] state. This may be necessary in rare cases where gARIM's busy state falls out of sync with the TNC's busy detector state.

In ARQ mode, pressing the <ESC> key to abort a connection results in a "dirty disconnect". Use <CTRL-X> to attempt a clean disconnect before resorting to <ESC>.

Using the command line

Open the program and press the spacebar to open the command prompt (or click it with the mouse), and enter a command.

gARIM

There are multiple uses for the command line.

Basic line editing features are available on the command prompt. The left and right arrow keys, HOME, END, DEL and backspace keys work as expected. This makes it easy to correct mistakes in typing, whether a entering a command or composing a message.

The command prompt has a history buffer which holds the last 15 unique commands entered. Use the UP and DOWN keys to browse command history when you want to reuse a previously sent command.

Sending commands to the TNC

A TNC must be attached. Press the spacebar to open the command prompt.

gARIM

Prefix the message with the '!' character. Press ENTER to send the command to the TNC. The command trace will appear in the TNC command view, followed by the TNC's response if it was a query. To set a TNC parameter, follow the command with the parameter, e.g. !CWID TRUE. To query a TNC parameter, send the command without any argument, e.g. !CWID. Complete control over the TNC is available using this interface. ARDOP TNC commands are documented in the Host Interface Spec for the ARDOP TNC by Rick Muething, KN6KB and available in the files area of the ARDOP users group at groups.io.

Viewing and changing TNC settings

TNC parameters are set in the [tnc] section of the garim.ini configuration file and loaded when attaching to a TNC. However, some of these settings can be modified on-the-fly from the TNC menu:

gARIM

For basic settings choose TNC->Basic Settings... from the main menu:

gARIM

For FEC settings choose TNC->FEC Mode Settings... from the main menu:

gARIM

For ARQ settings choose TNC->ARQ Mode Settings... from the main menu:

gARIM

When attached to a TNC, any TNC parameter may be queried or changed at the command prompt using bang commands. These are prefixed with the '!' character and are sent directly to the TNC. For example, !SENDID queries the SENDID parameter, and !BUSYDET 5 sets the BUSYDET parameter to '5'. ARDOP TNC commands are described in the ARDOP_2 Protocol Native TNC Commands document by KN6KB. The current version is located in the files section of the ARDOP Developers Group.

Composing a message (to outbox)

Whether or not attached to a TNC, messages can be composed and stored in the message outbox. Choose Message->Compose... from the main menu to open the Compose Message dialog box:

gARIM

If not in ARQ mode, enter the call sign of the destination station in the To Station: field, then enter the message text into the text editor window. Press Save to Outbox to save the message, or Send to transmit it to the destination station.

The Use compression option is available only in an ARQ session. In that case the To station: field is automatically populated with the call sign of the connected station.

gARIM

Enter the message, then press Save to Outbox to save the message, or Send to transmit it to the connected station.

Press Cancel to cancel the message.

Pinging another station

A TNC must be attached and the RF channel must not be busy. Choose Ping->Send Ping... from the main menu.

gARIM

Enter the call sign of the target station, and the number of ping repeats desired. This is the number of times the PING packet will be sent in the absence of a response from the target station before the TNC "gives up". The minimum repeat count is 2 and the maximum is 15. The response from the target station will include a signal report including the signal-to-noise ratio and a constellation quality figure ranging from 0-100%.

If the RF channel is busy, gARIM won't send the ping, and an error message will be shown on the status bar.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the ping call nbr command where call is the call sign of the target station, and nbr is the number of pings to send in the absence of a response. nbr must be in the range 2-15.

Using Pilot Pings

Pilot pings are ARDOP PING frames automatically sent in advance of an ARIM message or query transmission or ARQ connect request to test the RF path to the target station. If the signal constellation quality report from the target station meets a preset threshold, the message transmission proceeds; if not then it is canceled. This prevents hopeless attempts at message transmission from tying up the frequency in marginal conditions. The PING/PINGACK cycle is very short compared to the length of a typical FEC message transmission so the additional overhead is low, but the potential improvement in efficiency of channel use is high. Pilot pings are never sent in advance of ARIM messages directed to the net call.

Pilot Ping parameters are set in the [arim] section of the garim.ini configuration file, but can also be modified on-the-fly so the operator can adapt to changing conditions. Choose Ping->Pilot Ping Settings... from the main menu.

gARIM

These settings can also be modified on-the-fly from the gARIM command prompt.

ARQ: Connecting to a remote station

gARIM can act as an ARQ client or server, interoperating with ARDOP Chat or another gARIM (or ARIM) station for keyboard to keyboard chat. gARIM may also be used as an ARQ client to connect to a BPQ BBS with a ARDOP port.

A TNC must be attached and the RF channel must not be busy. Choose ARQ->Connect... from the main menu.

gARIM

Enter the call sign of the target station, and adjust Nbr repeats as desired. This is the number of times the ARQCALL frame will be sent in the absence of a response from the target station before the TNC "gives up". The minimum repeat count is 3 and the maximum is 15. ARQ bandwidth is the connection bandwidth (ARQBW) specifier. It can be one of 200, 500, 2500 or ANY. If ANY, ARIM will attempt to connect using each ARQBW setting in succession, starting with the current ARQBW setting. This is useful if the ARQBW setting of the remote station is unknown. Connect requests and responses are displayed in the monitor view.

ARDOP 2 TNCs reject connection requests if the ARQBW setting of the calling station exceeds that of the remote station. For this reason, gARIM optionally lets the operator specify an ARQ connection bandwidth to override the local ARQBW setting and allow the connection. Alternatively, the operator can select the ANY specifier to make gARIM discover a workable ARQBW setting automatically (i.e. negotiating the connection bandwidth itself). In this example the proper ARQBW is known to be 500.

gARIM

If the RF channel is busy, gARIM won't send the connection request, and an error message will be shown on the status bar.

When the connection is made, gARIM will be in ARQ mode, where text entered at the command prompt is sent directly to the remote station rather than processed as an ARIM command. The line editing and history recall features of the command prompt work as usual but the '!' prefix won't work to send commands directly to the TNC, and the ':' prefix won't work to send unproto FEC transmissions.

All text sent and received will be displayed on the Traffic Monitor, and the status bar will show the call sign of the remote station, the negotiated max connection bandwidth and the current TNC state.

The local files, message inbox, message outbox and sent messages viewers work as usual in ARQ mode. Files can be uploaded to the remote station from the local files viewer. Previously composed messages can be sent to the remote station from the message outbox viewer, and messages can be forwarded to the remote station from the message inbox and sent messages viewers.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the conn call nbr [bw] command where call is the call sign of the target station, nbr is the number of connection requests to send in the absence of a response, and the optional bw parameter sets the connection bandwidth. nbr must be in the range 3-15 and bw must be one of 200, 500, 2500 or any.

To disconnect, press <CTRL-X>, choose ARQ->Disconnect from the main menu, or enter the special command '/dis' at the command prompt and press ENTER.

gARIM

You'll be prompted to confirm:

gARIM

Press Yes and a clean disconnect will be attempted.

gARIM

ARQ behavior is controlled by these parameters in the [tnc] section of the garim.ini configuration file:

These parameters can also be modified on-the-fly from the gARIM command prompt by the operator, or from the TNC menu.

If pilot pings are enabled they will apply to ARQ connection requests, so that the RF path to the remote station can be tested in advance. If the pilot pings fail, the connection attempt will be canceled.

ARQ: Sending queries to the remote station

When connected to a gARIM (or ARIM) station, the following queries may be sent to the remote station:

Choose Query->Send Query... from the main menu.

gARIM

Select the desired query and press OK. Here we see the response:

gARIM

ARQ: Sending messages to the remote station

When connected to a gARIM (or ARIM) station, single-line messages can be sent using the /sm [-z][msg] command where the -z option invokes compression, and msg is the message text. This is convenient when the message is short and you wish to bypass the message composer. Press the spacebar to open the command prompt and enter the command like this:

gARIM

The remote station saves the message to its inbox and returns an /OK response to confirm receipt. A copy will be stored in your sent messages mailbox.

gARIM

For longer, multi-line messages, choose Message->Compose Message... from the main menu to open the Compose Message dialog box:

gARIM

Enter the message. Check Use compression if you wish to have the message compressed to reduce transfer time.

To cancel a message you've started, press Cancel to close the message composer view. Press Send to send the message to the connected station.

gARIM

The remote station saves the message to its inbox and returns an /OK response to confirm receipt. A copy will be stored in your sent messages mailbox.

While the upload is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the upload, press CTRL-X to close the ARQ connection.

If the remote gARIM (or ARIM) station encounters an error saving the message, it returns an /ERROR response and the message is discarded.

Existing messages in a local mailbox can also be sent to the remote station from one of the message view tabs.

Previously composed messages stored in the outbox can be sent to the remote station. Select the Msg Outbox tab:

gARIM

Right-click on the desired message header and choose Send... from the pop-up menu. This opens the Send Message dialog box:

gARIM

Check Use compression if you wish to compress the message to reduce transfer time. Press OK to send the message to the connected station. This is a more efficient method than composing the messages during the ARQ session itself.

Messages in the inbox can be forwarded to the remote station in the same manner. Select the Msg Inbox tab and right-click on the desired message header. Choose Forward... from the pop-up menu.

Messages in the sent messages mailbox can also be forwarded to the remote station. Select the Sent Messages tab and right-click on the desired message header. Choose Forward... from the pop-up menu.

If the remote gARIM (or ARIM) station encounters an error saving the message, it returns an /ERROR response and the message is discarded.

ARQ: Downloading messages from the remote station

In an authenticated ARQ session, you can retrieve messages addressed to your station that are queued in the remote station's outbox. This is useful if you are on the air only intermittently; the operator at the remote station can compose a message when convenient, leaving it in the outbox for you to download later.

To list your messages, choose ARQ->Get My Message Listing from the main menu.

The remote station responds:

gARIM

In this example, the command triggers the mutual authentication process automatically. After that, the listing is received. The messages are listed in chronological order (oldest first).

To download the listed messages, choose ARQ->Get My Messages... from the main menu. The Get My Messages from Remote Station dialog box opens:

gARIM

Select the maximum number of messages to download, and check Use compression if you wish to compress the messages to reduce transfer time. Press OK to start the message download to the local station.

gARIM

The progress of the download is reported as each message is received. As each message is received, the receiving station stores the message in its inbox and sends a /OK response to confirm receipt. The sending station then deletes the message from its outbox. If the either station encounters an error, it sends an /ERROR response to the other and the download is canceled. In that case the message is not deleted from the outbox at the sending station.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the download, press CTRL-X to close the ARQ connection.

ARQ: Listing shared files on the remote station

When connected to a gARIM (or ARIM) station, choose ARQ->Get File Listing... from the main menu to download a listing of shared files it offers. The Get File List from Remote Station dialog box opens:

gARIM

Enter the path of the remote directory to list or leave it blank for a listing of the root shared files directory. Check Use compression if you wish to compress the listing to reduce transfer time. Press OK to start the file listing download.

gARIM

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the download, press CTRL-X to close the ARQ connection.

When the download is finished the file listing appears in the Remote Files tab:

gARIM

The contents of the directory are listed, one to a line, and the remote file path is shown at the bottom of the view. For files, the name and size in bytes are shown. For subdirectories, the name is shown. Access-controlled subdirectories are indicated with the ! (bang) character like this: !DIR.

To read a file, right-click on its listing and choose Read from the pop-up menu.

gARIM

The file will be downloaded and printed to the Traffic Monitor view:

gARIM

To download a file, right-click on its listing and choose Get... from the pop-up menu.

gARIM

The Get Remote File dialox box opens:

gARIM

Check Use compression if you wish to compress the listing to reduce transfer time. To download the file to a directory other than the default download directory, enter its path in the To local directory: field or click the browse button and navigate to the desired directory in the Select Local Destination Directory dialog box. The destination directory must made visible by an add-files-dir configuration file parameter at the local station. If no destination directory is specified, the file is stored in the download subdirectory in the local station's shared files root directory. Press OK to get the file.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the download, press CTRL-X to close the ARQ connection.

To list a subdirectory, right-click on its listing and choose Open Directory... from the pop-up menu.

gARIM

The Open Remote Directory dialog box opens:

gARIM

Check Use compression if you wish to compress the listing to reduce transfer time. Press OK to start the file listing download.

The directory listing will be downloaded and displayed in the Remote Files tab, replacing the previous contents.

gARIM

The Remote Files tab is automatically cleared when the ARQ session is closed.

The mutual authentication process will be triggered automatically if a access-controlled directory is listed when the session is not yet authenticated.

ARQ: Reading files from the remote station

When connected to a gARIM (or ARIM) station the shared text files it offers can be read in the Traffic Monitor view. Only text files and dynamic files with text output can be printed to the screen.

To read a file, choose ARQ->Read File... from the main menu to open the Read File from Remote Station dialog box:

gARIM

Enter the name of the file, which can include a path to a subdirectory under the root shared files directory on the remote station. In this example the file test.txt is known to be located in the directory net. Press OK to start reading.

gARIM

The text is printed the the Traffic Monitor view line by line as it is received.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

ARQ: Downloading files from the remote station

When connected to a gARIM (or ARIM) station any shared files it offers can be downloaded. Both text and binary file types can be transferred over the ARQ connection. A compression option can be invoked to reduce transfer time for many file types, and you can specify a destination directory at the local station other than the default.

To download a file, choose ARQ->Get File... from the main menu to open the Get File from Remote Station dialog box:

gARIM

Enter the name of the file and check Use compression if you wish to compress the file to reduce transfer time. To download the file to a directory other than the default download directory, enter its path in the To local directory: field or click the browse button and navigate to the desired directory in the Select Local Destination Directory dialog box. The destination directory must made visible by an add-files-dir configuration file parameter at the local station. If no destination directory is specified, the file is stored in the download subdirectory in the local station's shared files root directory. Press OK to start the download.

gARIM

The progress of the download is reported as each data frame is received. When it's complete an /OK response is sent to the remote station to confirm receipt. If the remote ARIM station encounters an error sending the file, it returns an /ERROR response and the download is canceled.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the download, press CTRL-X to close the ARQ connection.

ARQ: Uploading files to the remote station

When connected to a gARIM (or ARIM) station local files can be uploaded to the remote station. Both text and binary file types can be transferred over the ARQ connection. A compression option can be invoked to reduce transfer time for many file types, and you can specify a destination directory at the remote station other than the default.

To upload a file, choose ARQ->Send File... from the main menu to open the Send File to Remote Station dialog box:

gARIM

Enter the name of the file or click the browse button and select the file in the Select File to Send dialog box. Check Use compression if you wish to compress the listing to reduce transfer time. To upload the file to a directory other than the default download directory at the remote station, enter its path in the To remote directory: field This path must be relative to the shared files root directory, e.g. contests/2016 and must made visible by an add-files-dir configuration file parameter at the remote station. Press OK to start the upload.

gARIM

The progress of the upload is reported as each data frame is sent. When it's complete an /OK response is received from the remote station to confirm the file was saved. If the remote gARIM (or ARIM) station encounters an error receiving the file, it returns an /ERROR response and the upload is canceled.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

While the upload is in progress no text or commands are accepted from the command prompt. This condition is indicated by a ! character seen in the status bar indicator area and yellow background color:

gARIM

To cancel the upload, press CTRL-X to close the ARQ connection.

ARQ: Session Authentication

The optional Mutual Authentication feature provides a way to verify the identities of the stations in an ARQ session. This works by making each station prove to the other that it possesses a shared secret (password) known only to the two stations involved. This is done using a Digest Access Authentication scheme very similar to that specified in RFC 2069 with the exception that the MD5 hash function is replaced by the more modern and secure Blake2 hash function. The exchange of proofs is accomplished without sending the password itself over the air. The process is automatic and requires no operator intervention. This feature can be used to:

Once an ARQ connection is established, the operator can invoke the mutual authentication process pre-emptively. If it succeeds, the identity of the remote station is proven and the operator can read, upload or download files with confidence. If it fails, because one station or the other doesn't know the shared secret (password), the operator is presented with a warning message and given the choice of either continuing or terminating the ARQ session.

For example, to authenticate pre-emptively, choose ARQ->Authenticate from the main menu.

gARIM

The remote station sends a challenge which is the first of 3 messages (A1, A2 and A3) exchanged during the authentication process.

gARIM

If the remote station cannot authenticate your station, you are alerted and asked if you want to disconnect:

gARIM

Likewise, if your station cannot authenticate the remote station, you are alerted and asked if you want to disconnect:

gARIM

In either case the problem is likely to be missing or incorrect password digest file entries.

If you prefer to use the keyboard, press <SP> to open the command prompt and enter the /auth command to authenticate.

The authentication challenge/response protocol

  1. The process begines when the operator at one station (the client), connects to another station (the server) and: or:
  2. At the server station, gARIM receives the command and recognizes that authentication is required. It searches its password digest file for an entry with the client station's call sign as the client and its own call sign as the server. If it cannot find such an entry, it responds with /EAUTH and the operator at the client station is informed that authentication has failed. If gARIM does find such an entry, it responds with an authentication challenge in the form of the /A1 command. The challenge includes an opaque nonce, a token whose content it controls and which must be incorporated into the response made by the client station.
  3. At the client station, gARIM receives the /A1 command. It searches its password digest file for an entry with its own call sign as the client and the server station's call sign as the server. If it cannot find such an entry, it responds with '/EAUTH' and the operator at the client station is informed that authentication has failed. If the needed entry is found, gARIM computes a response token which proves that it knows the shared secret. The response is: where: Thus the response to each challenge is unique, in a way dependent on the nature of the request and the nonce issued by the challenger. This makes "replay" attacks difficult to mount and recovery of the password from the response token computationally infeasible. gARIM sends the response token plus a challenge nonce to the server station in the form of the /A2 command.
  4. At the server station, gARIM receives the /A2 command and checks the challenge response token it contains. It does this by computing the response token it expects using the password digest token (HA1) stored in the password digest file it owns. It compares this with the response token received from the client station. If they don't match, then the client station must not have the same password digest that gARIM has stored locally. In this case gARIM will send /EAUTH to the client station where the operator will be informed that authentication has failed. If they match, then the client station has proven its authenticity and gARIM will send a response to the challenge contained in the /A2 command. As before, this is computed as H(HA1:nonce:HA2), using the challenge nonce received from the client station. It sends this response to the client station in the form of the /A3 command.
  5. At the client station, gARIM receives the /A3 command and checks the challenge response token it contains. It does this by computing the response token it expects using the password digest token (HA1) stored in the password digest file it owns. It compares this with the response token received from the server station. If they don't match, the server station must not have the same password digest that gARIM has stored locally. In this case gARIM will inform the operator that authentication has failed. If they match, then the server station has proven its authenticity and gARIM re-sends the command that triggered the process, unless it was the /auth command. In that case there is no work to do, so gARIM simply sends the /OK response to signal that the mutual authentication is complete.

To strike a reasonable balance between security and the "air time" cost of the challenge/response data exchanges, challenge nonces contain 6 bytes of data and the Blake2 response hash is truncated to 21 bytes, or 168 bits (big enough for excellent collision resistance). These are sent in base64 encoded form making the over-the-air sizes 8 and 28 bytes respectively.

ARQ: File access control

Shared files directories at a station can be designated as access-controlled with the ac-files-dir parameter in the garim.ini configuration file. These resources are available only to stations that successfully authenticate themselves in an ARQ session. By default, the authentication process is triggered automatically on the first attempt by a station to access a controlled resource. Here is an example:

gARIM

The operator at NW8L connects to KA8RYU and reads the space weather report. Next he attempts to download a access-controlled file, admin/contact-list.txt. This triggers an authentication challenge from KA8RYU in the form of the /A1 command. The mutual authentication succeeds, so the download command /FGET is automatically repeated and the file is downloaded. Note the + character appended to KA8RYU's call sign in the status bar. This indicates that the ARQ session is authenticated.

If mutual authentication succeeds, subsequent accesses of controlled resources on the remote station proceed normally.

Alternatively, the operator at NW8L can send the authenticate the remote station pre-emptively before attempting to access controlled directories and their contents. In this case, if station KA8RYU is unable to find a password digest file entry for NW8L, it sends the /EAUTH response and the operator at NW8L is alerted:

gARIM

Otherwise the authentication process proceeds as usual.

Note: shared files directories defined by add-files-dir parameters in the garim.ini configuration file are not access-controlled. These are accessible by any station in ARQ and FEC mode operations. Likewise, the root shared files directory is always accessible by any station for file listing, uploads and downloads.

ARQ: Password management

Passwords are created within gARIM and stored in digest ("hashed") form in a file. Passwords are hashed with a salt (the call signs of the corresponding stations), so that any given password results in unique hash for different call sign pairs. This hash is identical to the HA1 term used in the digest authentication scheme, so it can be read out of the password digest file when needed, making it unnecessary to store the original password. Mathematically, the Blake2 hash function is a strong one way function; it is computationally infeasible to recover the password from the hash. Because the password hash is stored in a file the authentication process can operate without operator intervention; there's no need to remember and enter the password each time.

In the context of an ARQ session, the term client refers to the station where an operator triggers the authentication process by:

When this happens the other station assumes the role of server and responds with an authentication challenge. These definitions imply that an operator is always present at the client station, but not at the server station, which is assumed to be operating automatically. However, once an ARQ connection is established between two stations, the operator at either end can seize the client role by being the first to trigger the mutual authentication process.

Let's assume that client call sign is KA8RYU, and the server call sign is NW8L. Choose ARQ->Create or Change Auth Password... from the main menu to open the Create or Change Auth Password dialog box. Enter the call sign of the client station, the call sign of the server station, and the password:

gARIM

Press OK to store the password.

gARIM

The operation will be confirmed.

This command must be executed at both stations to store the password digest on each. If this is done, KA8RYU can connect to NW8L and successfully authenticate if challenged. However, this doesn't mean that the reverse is true: NW8L can't connect to KA8RYU and do the same. To make this possible the process must be repeated at each station with NW8L specified as the client, and KA8RYU as the server:

gARIM

Now either station can connect to the other and play the role of client to the other station's role of server in the authentication process. Note that a different password is used; this is the best practice. If we read the arim-digest password digest file at either station by choosing File->View Auth Password File... from the main menu we see the newly created password entries:

gARIM

There are two entries, one for KA8RYU as client and NW8L as server, and another for NW8L as client and KA8RYU as server. This allows both one-way and two-way relationships to be defined. For instance, a station serving as a document repository can issue passwords to multiple stations who connect to it as clients and access the controlled files it offers. However, no such password is issued to the repository station by the client stations; it cannot connect to any of them in the client role and authenticate for the purpose of accessing any controlled resources they publish.

To protect against accidental disclosure of password digest file contents, any file named 'arim-digest', or variations like 'arim-digest.bak', no matter where located in the file system, are protected against access by a remote station. Avoid easy-to-guess passwords, and never include the call signs of the client or server stations in the password. While the base64 encoded Blake2 digest (HA1) may look quite random, it contains only as much entropy as the original password, so choose passwords well. Note: passwords are case sensitive!

Choose ARQ->Delete Auth Password... from the main menu to delete a password digest from the arim-digest file. The Delete Auth Password dialog box opens:

gARIM

Let's assume we want to delete the password digest for client-call KA8RYU, and server-call NW8L. Enter these calls and press OK You will be prompted to confirm the deletion:

gARIM

Press Yes to delete the password digest from the file.

FEC: Sending an unproto message

A TNC must be attached and the RF channel must not be busy. Press the spacebar to open the command prompt.

gARIM

Prefix the message with the ':' character. Press ENTER to send the message out over the air as raw ARDOP FEC frames, rather than being formatted as an ARIM message. The message will appear in the monitor view tagged with the [U] indicator.

If the RF channel is busy, gARIM won't send the unproto message, and an error message will be shown on the status bar.

FEC: Sending a message (to TNC)

When attached to a TNC, single-line messages can be sent using the sm call [msg] command, where call is the call sign of the recipient and msg is the message text. This is useful when the message is short and you wish to bypass the message composer. Press the spacebar to open the command prompt and enter the command like this:

gARIM

The message will be sent immediately after pressing the ENTER key to complete the command. A copy will be stored in your sent messages mailbox.

If the RF channel is busy, gARIM won't send the message, and an error message will be shown on the status bar.

For longer messages, choose Message->Compose... from the main menu.The message composer opens:

gARIM

Enter the call sign of the destination station and then the message. When done, press Send to start transmitting the message. a new line to close the message composer view to transmit the message. A copy will be stored in your sent messages mailbox.

gARIM

The Traffic Monitor shows the outbound message and the inbound ACK from the recipient station.

To cancel a message you've started to send, press <ESC> to abort the transmission and discard the message. You are alerted and asked if you want to store the message to the outbox:

gARIM

Press Yes to store the message to the outbox, No to discard it.

If the TNC is busy when the message is sent, the message will be stored in the outbox automatically. If the message send fails for some reason (NAK, ACK timeout, etc.), you are alerted and asked if you want to store the message to the outbox:

gARIM

Press Yes to store the message to the outbox, No to discard it.

FEC: Working with the message inbox

Select the Msg Inbox tab.

gARIM

This is a listing of headers for messages received. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

To read a message, right-click its header line and choose Read... from the pop-up menu:

gARIM

This opens the message viewer.

gARIM

Press Done to quit. Shortcut: double-click a header line to read the message.

To save a message to a disk file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

gARIM

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

When connected to a TNC, you can forward a message in the Recents view to another station. Right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

gARIM

Enter the call sign of the destination station and press OK to forward the message. The Use compression option is only available in ARQ mode. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Note: the automatic message purge process runs whenever gARIM is started. This discards messages whose age in days exceeds the limit set by the max-msg-days parameter in the [arim] section of the garim.ini configuration file. Set it to 0 to disable automatic message purging. The default setting is 0.

FEC: Working with the message outbox

Select the Msg Outbox tab.

gARIM

This is a listing of headers for outbound messages ready to be sent. Previously composed messages and messages saved after a failed send operation are stored here. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

To read a message, right-click its header line and choose Read... from the pop-up menu:

gARIM

This opens the message viewer.

gARIM

Press Done to quit. Shortcut: double-click a header line to read the message.

To save a message to a disk file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

gARIM

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

When connected to a TNC, you can send a message in the outbox to another station. Right-click its header line and choose Send... from the pop-up menu. The Send Message dialog box opens:

gARIM

Press OK to send the message. The Use compression option is only available in ARQ mode. In that case the message is sent to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Note: the automatic message purge process runs when gARIM is started. This discards messages whose age in days exceeds the limit set by the max-msg-days parameter in the [arim] section of the garim.ini configuration file. Set it to 0 to disable automatic message purging. The default setting is 0.

FEC: Working with sent messages

Select the Sent Messages tab.

gARIM

This is a listing of headers for messages previously sent. Headers contain the following information, from left to right:

To read a message, right-click its header line and choose Read... from the pop-up menu:

gARIM

This opens the message viewer.

gARIM

Press Done to quit. Shortcut: double-click a header line to read the message.

To save a message to a disk file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

gARIM

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

When connected to a TNC, you can forward a message in the Recents view to another station. Right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

gARIM

Enter the call sign of the destination station and press OK to forward the message. The Use compression option is only available in ARQ mode. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Note: the automatic message purge process runs whenever gARIM is started. This discards messages whose age in days exceeds the limit set by the max-msg-days parameter in the [arim] section of the garim.ini configuration file. Set it to 0 to disable automatic message purging. The default setting is 0.

FEC: Query another station for information

A TNC must be attached and the RF channel must not be busy. Choose Query->Send Query... from the main menu to open the Send Query dialog box:

gARIM

Enter the call sign of the target stations and select a query from the list. Query is one of these:

The target station will send the requested information in a response message.

gARIM

The response message will appear in the monitor view tagged with the [R] indicator. It will be stored in the message inbox for later viewing, and also appear in the Recents list.

If the RF channel is busy, gARIM won't send the query, and an error message will be shown on the status bar.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the sq call query command where call is the call sign of the target station, and query specifies the query to send.

FEC: Retrieving files from another station

In FEC mode you can retrieve a file from another station with the file query. The message is stored into the inbox where it can be viewed or saved to disk. If you aren't sure about the file name, you can also get a listing of available files with the flist query.

These operations are described in the FEC: Query another station for information topic.

NOTE: the maximum file size is set by the max-file-size parameter in the [arim] section of the garim.ini configuration file. The file list returned by the flist query is filtered so that only static files less than the max size are listed, and the output of dynamic files is limited to the max size. At this time the absolute maximum allowed is 16384 bytes. The location of the shared files root directory is set by the files-dir parameter in the [arim] section of the garim.ini configuration file.

FEC: Using message send repeats

In difficult conditions it may be helpful to enable automatic repeats of messages if they are nak'd or an ACK timeout occurs. Three parameters control message send repeat behavior:

These parameters are set in the [arim] section of the garim.ini configuration file, but can also be modified on-the-fly from the gARIM menu so operator an adapt to changing conditions. Choose Message->Send Repeat Settings... from the main menu to open the Message Send Repeat Settings dialog box:

gARIM

Adjust Nbr of repeats on NAK to set the number of times a message send will be repeated in the absence of an ACK response from the recipient. Adjust Message ACK timeout (secs) to set the message ACK timeout in seconds. Check Downshift FEC mode on repeat to enable FEC mode downshifting when repeating a message, uncheck to disable downshifting.

When done, press OK to apply the settings. The change will be confirmed by a message on the Status Bar.

FEC: Beaconing

Beaconing can be configured for each TNC by the btime parameter in the relevant [tnc] section of the garim.ini configuration file. This parameter defines the beacon repeat time in minutes, with '0' meaning that beaconing is disabled. The beacon status indicator in the Status Bar shows the repeat time when beaconing is enabled, or "OFF" when disabled.

When attached to a TNC, the beacon repeat time can be modified on-the-fly from the gARIM menu. Choose Beacon->Repeat Time... from the main menu to open the Beacon Repeat Time dialog box:

gARIM

Adjust Beacon repeat time (mins) to set the beacon repeat time in minutes.

To test the beacon, choose Beacon->Send Beacon from the main menu. If the RF channel is busy, gARIM won't send the beacon, and an error message will be shown on the status bar. If the beacon is enabled, then gARIM will try again once, 2 minutes later. If the RF channel remains busy, gARIM gives up and schedules the next beacon for btime minutes later.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the btest command to test the beacon.

RF channel busy detect

gARIM listens for BUSY notifications from the ARDOP TNC, which are sent to the host program when a signal is detected in the RF channel. When the channel is busy, gARIM displays the [RF CHANNEL BUSY] indicator in the status bar:

gARIM

gARIM will check the RF channel busy status when the operator initiates any of these actions:

If the RF channel is busy, gARIM will cancel the operation and an error message will be shown on the status bar. If sending a message, the operator is prompted to save it to the outbox to be sent later. This helps prevent collisions between transmissions on a busy channel, for example during net operations.

The TNC does not send BUSY notifications to the host program during an ARQ session.

The ARDOP TNC's busy detect feature is influenced by these configuration parameters:

In some cases, gARIM may not receive a BUSY FALSE notification when one is expected. This can leave gARIM stuck in the [RF CHANNEL BUSY] state, and attempts to start a new operation will fail. If this happens, the operator can recover by pressing the <ESC> key to reset gARIM's busy state.

Working with the local shared files viewer

Select the Local Files tab.

gARIM

The viewer opens in the shared files root directory defined by the files-dir parameter in the [arim] section of the garim.ini configuration file. The directory path is shown in the title of the viewer window.

The contents of the directory are listed, one to a line. For files, the name, size in bytes and the last-modified date are shown. For subdirectories, the name and last-modified date are shown. Access-controlled subdirectories defined by the ac-files-dir configuration file parameter are indicated with the ! (bang) character like this: !DIRECTORY.

To send a file to another station, right-click its listing and choose Send File... from the pop-up menu:

gARIM

The Send File dialog box opens.

In FEC mode it looks like this:

gARIM

Enter the call sign of the destination station and press OK to send the file as an ARIM message.

In ARQ mode it looks like this:

gARIM

Check Use compression if you wish to compress the file to reduce transfer time. To upload the file to a directory other than the default download directory at the remote station, enter its path in the To remote directory: field This path must be relative to the shared files root directory, e.g. contests/2016 and must made visible by an add-files-dir configuration file parameter at the remote station. Press OK to start the upload.

To open a file for viewing or editing, right-click its listing and choose Open File... from the pop-up menu. The Open Text File editor window opens:

gARIM

If you make changes, press Save to save them to file and close the editor. Shortcut: double-click a file listing to open it for viewing or editing.

To open a directory, right-click its listing and choose Open Directory from the pop-up menu:

gARIM

The contents of the tab will be replaced with a listing of the newly opened directory. The listing includes the parent directory (..) as item number 1. Shortcut: double-click a directory listing to open it.

To reload a directory listing, right-click and choose Reload Directory from the pop-up menu.

Viewing and editing files

Text files listed in the shared files viewer can be opened for viewing and editing from the gARIM menu. Choose File->Open Text File... from the main menu. The Open Text File dialog box opens. Select the file, then press OK to open the file in the Open Text File editor window. If you make changes, press Save to save them to file and close the editor.

Serving dynamic files

Dynamic files are used to return output from a script or system command executed by gARIM in response to a file query.

Dynamic file aliases appear in listings of the shared files root directory at a remote station. Because the size of the output is not known in advance, no file size is shown; instead the DYN identifier appears, like this:

gARIM

Here's a sample of the spwxfc dynamic file output as seen in an ARQ session:

gARIM

Dynamic file aliases are defined in the [arim] section of the garim.ini configuration file. The format is alias:command where alias is the name used to access the file and command is the invocation of the command or script, separated by a : (colon) character. For example:

dynamic-file = spwxfc:python /home/nw8l/scripts/forecast.py

Make sure that alias is unique among the other dynamic file definitions and file names in the shared files directory. Use absolute paths to script files when gARIM is built from source and installed. Relative paths can be used for "portable" binary installations where the script files are contained in same directory as the arim executable file. You may define no more than 16 dynamic files.

In response to the query sq file alias, command will be executed in a shell and its output returned in the response. command can be a batch file, a script invocation like python myscript or a system command like date or uname -a. The output size in bytes is limited by the max-file-size parameter in the [arim] section of the garim.ini configuration file. Errors generated by dynamic file scripts are written to a file named dyn-file-error.log in the log directory.

Logging

Two logs can be enabled or disabled in the garim.ini configuration file; the traffic log and the debug log. The traffic log is enabled by default and logs the content of all ARIM and ARDOP data frames sent and received by the TNC, with timestamping of each entry. The debug log is disabled by default. It logs all TNC commands sent and received by the gARIM program as well as exceptions encountered in operation like data wait timeouts, communication errors etc.

Set the traffic-log parameter in the [log] section of the garim.ini configuration file to TRUE to enable traffic logging and to FALSE to disable it. Set the debug-log parameter in the [log] section of the garim.ini configuration file to TRUE to enable debug logging and to FALSE to disable it.

Another log file, the dynamic file error log, is always enabled. It logs error messages from scripts or programs that generate dynamic file text output.

Logs are kept in the logs subdirectory of the ARIM working directory. They are automatically rotated every 24 hours. The file name format is name-YYYYMMDD.log where name is either traffic, debug or dyn-file-error, followed by the date, e.g. traffic-20161114.log.

To view a log file, choose File->View Log File... from the main menu. The Select Log File dialog box opens in the gARIM log file directory. Select a log file and press OK to open it for reading.

Copyright © 2016, 2017, 2018 by Robert Cunnings NW8L.  Last modified: 20 Aug 2018.