LinPac - Packet Radio Terminal for Linux

Version 0.28

(c) 2020 - 1998 by David Ranch KI6ZHD


User manual

Index

1 What is LinPac

2 First configuration

3 LinPac controls
3.1 Keyboard
3.2 Entering commands
3.3 Initiating a connection
3.4 Receiving and sending files
3.5 Remote commands
3.6 Character encoding
3.7 Huffman compression

4 Variables
4.1 Special variables

5 Station database
5.1 The station.data file format
5.2 The 'Name' command
5.3 Using the database

6 About macros
6.1 Creating macros
6.2 Commands used in macros
6.3 Special system macros

7 Creating new commands

8 Standard applications
8.1 File transfer protocols
8.2 Automatic password generation
8.2.1 Login passwords
8.2.2 Sysop and general use passwords
8.3 Utilities for mail exchange
8.4 Mail client
8.5 Logbook

9 Command line options

10 Copying

Appendix A: List of LinPac commands

Appendix B: Linpac FAQ / Questions and Answers / Getting more help

Appendix C: Errata


1 What is LinPac

LinPac is a packet radio terminal for Linux that allows wide configurability and easy addition of new functions and special functions needed by the user. The aim is to minimize the amount of 'hard coded' functions and create a complete set of applications that can be easy expanded and/or completely reconfigured.

All functions described in this manual match the standard configuration that comes with the distribution package.

2 First configuration

When linpac is started for the first time on your computer, it automaticaly creates the directory called LinPac in the running user's home directory. This directory will contain the user's personal LinPac configuration settings. After creating this directory, LinPac asks for basic callsign, port and other information and prepares a useable configuration for you. An example setup dialog is as shown, where we are using the bogus call "n0call" logging into the local home BBS "n0ary-1":

The above information is then stored in the $HOME/LinPac/macro/init.mac file as various 'functions'. These functions are based on the very simple interpreted language (actually it's not a language but something like the batch files in DOS). In the LinPac/macro directory are all the scripts written in this language. The init.mac macro is loaded at start of loading Linpac and contains the commands to setup the callsigns and other settings. You can modify this file to change the initial configuration of LinPac. Other macros can be run in LinPac as desired or required. The simplest case of a macro is a normal text file that is just printed to the screen (or sent to the remote peer) when executed. The language is described in chapter 6.

You may also want to review or change following macro files:

After this you should be able to make your first connection.

3 LinPac controls

After automatically running the LinPac setup routine, the main screen should appear. If you see a segmentation fault, please see Linux AX.25 issues with long predictable network interface names for a work around. Moving on, in Linpac's main interface in the standard configuraion, the screen is divided into five parts (described from the top of the screen to the bottom):

LinPac is mostly driven by commands. The commands are entered using the editor and must start with a colon (':') in the first column. Lines that don't begin with a colon are sent to the peer, if connected.

LinPac allows up to eight connections to be made simultaneously. For each connection one channel is used. You can switch between channels by pressing the F1 - F8 keys. Each has its own QSO window, status line and editor. The channel list and the monitor are common across all the channels.

There is a special channel invoked by pressing F10. This channel has no QSO window and doesn't allow making a connection. The text written is sent out immediately using UI frames (beacon).

3.1 Keyboard

The following list contains the important shortcuts:

Some applications (e.g. mailer) can use the whole screen. Each channel can run only one such application at a time. It's possible to switch to this application using Alt-<channel_number> (e.g. Alt-5) and switch back to terminal using F1 - F10.

3.2 Entering commands

Each command is invoked using its name. Some commands can be abbreviated. In this manual the mandatory part is always written in upper case. The remainder of the command name is optional. Some commands require some extra arguments. The arguments are written after the command and are separated by one or more spaces. If you want to enter an argument containing more than one word, that argument must be entered in quotation marks.

Examples:

Most of the commands work on the currently selected channel. If you want to execute the command on some other channel, you can enter the number of the channel this way. For example, to make an OUTGOING connection to destination OK0PAB on Linpac channel 5:

In this case the 'connect' command is executed on channel 5.

The complete list of commands with descriptions is available in Appendix A.

3.3 Initiating a connection

To initiate a connection the :Connect command is used. Just switch to the channel you want to use by pressing F1 - F8 and enter the following command:

:connect CALLSIGN

Replace the CALLSIGN with the real callsign of the station you want to connect. The command can be abbreviated to the first letter only. Example:

:c OK0PAB

This command will initiate the connecting sequence to OK0PAB. To close the connection, you can use the :Disconnect command by entering

:d

When your system has multiple radio ports, you can specify its name before the callsign like this:

:c 2:OK0PAB

This command will try to connect OK0PAB via port 2. When no port name is specified, the default one is used. Initially the default port is the first port in /etc/axports (your system AX.25 port configuration file). If you want to change the default port, just use the command :port.

:port 2

This will change the default port name to '2'. In some cases it is useful to set another default port for some selected channels. For this the variable CHN_PORT can be used (see chapter 4). When set, the content of this variable overrides the default port selection for the particular channel. For example, when you set the variable for channel 4 using

:set CHN_PORT@4 1

the port '1' will be used as the default one for the channel 4. For other channels, the previously set default port will be used.

3.4 Receiving and sending files

The standard distribution can receive files using plain text or binary transfer and using file transfer protocols YAPP and Autobin. LinPac will automaticaly start to receive the file when the peer begins to send using the YAPP or Autobin protocols. The 7+ files are automaticaly saved too. When you want to save the incoming text you have to use the command

:Write <filename>

The incoming text will be saved until you stop the saving using

:Write off

For receiving a plain binary file, the corresponding command :WBin can be used. This way of transferring binary files is not recommended; use the autobin or yapp protocol instead.

The following commands are available for sending files:

3.5 Remote commands

LinPac allows the remote user to enter commands. For remote control, all LinPac commands are available but there can be (and should be) some restrictions for each user.

The remote command must start with the // sequence. For example if some connected user sends you the text '//info' your terminal will send back the station information.

The remote commands can be disabled using the command :remote off and enabled by :remote on. You can also specify that only some commands be available for remote users. The default list of available remote commands is defined in the init.mac file (the DEF_RCMD line). It is also possible to enable various commands for each user. This is described in chapter 5.

3.6 Character encoding

Some countries use different national character encodings for some historical reasons. A user who has his Linux console configured for example for some of the standard ISO encodings may be incompatible with another one using a traditional encoding. To solve this LinPac allows the translation of the input and output of each channel using a translation table. The translation tables are stored in files *.ctt in the LinPac home directory.

All known encodings must be defined in the file called encodings in the LinPac home directory. This file contains a single line for each encoding that specifies its alias (name which will identify the encoding in LinPac), encoding name (an official name such as iso-8859-1) and optionally the name of the translation table file to be used (without the extension .ctt).

Note that LinPac does not support multi-byte encodings such as UTF-8 or other Unicode encodings.

The current encoding can be switched using the :TRanslate command separately for each channel. To specify the default encoding for each user you can add the line

ENC=<alias>

to the appropriate record in the station database. (The station database is described in chapter 5.) When no encoding is specified for the user, the default one is used. The default encoding alias is stored in the DEF_ENC@0 variable which is set in the macro init.mac.

When the conversion table is not specified in the encodings file LinPac only changes the name of currently used encoding but doesn't provide any conversion. However some applications (such as QLinPac which works in unicode) are able to do their own conversions.

3.7 Huffman compression

Some packet radio terminals and BBS software allows the compression of transferred text. When switched on, the sender does the compression of all data before sending them to the other station and the recipient has to decompress the data after receiving them. This makes the communication more reliable and reduces the load of the radio link.

The line compression in LinPac is activated using the :comp command. The compression is switched on using :comp on and switched off using :comp off. To ensure that the compression is activated or deactivated on both ends of the link simultaneously LinPac sends the remote command :comp 1 or :comp 0 to the other station automatically. The arguments 1 and 0 have the same effect as on and off, but they don't cause sending any command to the other station.

In the case in which the remote system doesn't support the :comp command it's necessary to switch on the compression on the remote system manually and then use the:comp 1 command in LinPac.

4 Variables

Each channel has its own set of variables. Some of the variables are used to store the configuration data. The user can create and remove variables and change the values of existing variables using following commands:

Some examples:

The name of the variable can contain the specification of the channel. For example the variable NAME@5 is the variable 'NAME' defined on channel 5.

When LinPac finds the character '%' followed by the name of variable, it automatically replaces this text with the value of the variable. Considering the previous example, the text %NAME will be replaced with John.

4.1 Special variables

There are some special internal variables that don't allow changing their value. Their value is set and changed directly by LinPac and these variables can be used to add some actual information to the text. The list follows:

Variables for use in macros only:

For example try to write following text in the editor and press enter:

The time is %T and the date is %D.

5 Station database

The station database holds various information about known stations. All the information is stored in the 'station.data' file and can be changed using the normal text editor or using the LinPac :Name command.

5.1 The station.data file format

The information about each station is written in a paragraph starting with the station callsign in square brackets. Each line in the paragraph contains one definition like:

<item_name>=<value>

A typical station information paragraph might look like this:

There are no mandatory items; the user can add various items depending on what information he wants to store. The current LinPac distribution uses following item names for standard information:

The standard LinPac configuration also uses these item names:

5.2 The 'Name' command

The :Name command is used to modify the station database. Running the command without arguments results printing the name of currently connected station. Arguments can be used to modify the data:

The command 'Name -i' prints all information about the station. When you need to change the information about a station other than the connected station, add the argument -c <callsign>.

Examples:

5.3 Using the database

After any connection is established, LinPac reads the information about the connected station from the database and creates the set of variables with names STN_<database_item_name> containing the values of the items. These variables can be used in macros as described below.

6 About macros

6.1 Creating macros

A macro is a LinPac command that is created using the macro language, and uses other LinPac commands to perform some action. A macro can be defined by creating the file macro/<command_name>.mac. It's possible to define an abbreviated form of the command; this is described in chapter 7. There are two ways to define a macro:

a) Text macros
This way is suitable for commands which are intended to produce a larger text output (for example station information). When executing this macro, each line that doesn't start with ':' is printed (sent out). All commands must start with the colon. This is suitable for modifying the text output using the IF ~ ELSE ~ ENDIF commands or for including some other commands.

b) Command macros
A command macro must start with the line
:MACRO <name>
Each line of a command macro is interpreted as a command (doesn't start with the colon and doesn't need to start at the begining of line). Text output is provided by the 'echo' command. This way is more synoptical and allows including comments that must start with the sequence ';;' and end at the end of the line.

A macro is called with its name. When the first arguments starts with the '@' symbol the macro is executed from the specified label. For example the command :convers @SEND will execute the macro 'convers.mac' from the label 'SEND' (see next chapter to see how to define the label).

6.2 Commands used in macros

A macro can contain all LinPac and user defined commands. There are also some special commands that can be used in macros only:

MACRO [name]
Start of the command script definition (see previous section).

LABEL <label_name>
Creates a label with specified name. In the command scripts the notation :<label_name> can be used.

GOTO <label_name>
Jump to specified label.

IF ~ ELSE ~ ENDIF
Conditional commands. There are two ways to specify a condition:

The following example shows how to use conditions and how to use the data from the station database. We want to create a macro that will greet the operator of the connected station with his nickname or with his name, if the nickname is not defined.

a) The solution using a text macro (the comments are actually not allowed in the text macros, they are here for explanation only)

b) The solution using a command macro

6.3 Special system macros

There are some special macros that are executed automaticaly by LinPac in some cases:

7 Creating new commands

A new command can be represented by a macro or by an external program (standard linux program or special LinPac application). Macros are placed in the $LINPACDIR/macro directory and external programs are placed in the $LINPACDIR/bin directory. In both of these directories is the file 'commands' that contains the list of commands in that directory. You should specify here the name of the file, the name of the command in LinPac (use upper case to specify the mandatory part of the command). It's not necessary to include the macros here if you don't want to define the abbreviation.

In case of external programs, it is also possibile to specify program flags. Currently the following flags are supported:

8 Standard applications

8.1 File transfer protocols

At present LinPac supports two protocols for transferring files:

Usage of these protocols is described in chapter 3.4.

LinPac can also automatically save incomming 7+ files. After saving all parts of a file LinPac tries to call the '7plus' program to decode the file. Received 7+ files are not removed automatically.

8.2 Automatic password generation

8.2.1 Login passwords

LinPac provides automatic replies to the login authorization requests for the following systems: F6FBB BBS (VE2BLY C_FILTER), BAYBOX, TNOS (numeric MD5). Each station which requests a login password must have an entry in the station database containing at least following fields:

A

BBS_prompt is the text which the BBS sends when requesting the authorization. Usually it looks like 'Password>' or 'OK0XYZ>'.

8.2.2 Sysop and general use passwords

LinPac provides automatic authorization to the following systems: F6FBB BBS (MD2 password), FLEXNET (older versions, the 'magic' numbers system and newer TheNet-like system), THENET and BAYBOX. Each station you want to authenticate with must have an entry in the station database. For password generation, the following fields must be set:

Known station types are:

In case of FBB the authorization algorithm can be chosen by setting the MD field in the station database:

When no value is set, MD2 algorithm is used.

After connecting to the station you want to authenticate with, the authorization sequence begins with the :PW command. LinPac will send the authorization command to the station and tries to answer the authorization request using your password. If the password is correct, authorization should finish successfully.

The PW command accepts the following parameters:

where

It's recommended that you create simple macros for frequently used authorizations that require special arguments to the PW command.

8.3 Utilities for mail exchange

LinPac contains support for exchanging messages with remote Kantronics PBBSs as well as F6FBB BBS systems. This support utilizies some tools from the ax25mail-utils so please install that package first. THe next step would be to configure Linpac and ax25mail-utils's configuration settings with the following variables either in Linpac's channel 0 or in Linpac's init.mac file:

Example #1: Kantronics KPC3:

To set the variable while in Linpac, the :SET command can be used. You can also put this same line (but without the colon) in Linpac's init.mac file:

The recommended place to set this variables is in the startup macro init.mac. The default version of this macro contains an example of setting these variables. After setting these variables, the following commands are available:

Example #2:

To set the variable while in Linpac, the :SET command can be used. You can also put this same line (but without the colon) in Linpac's init.mac file:

The recommended place to set this variables is in the startup macro init.mac. The default version of this macro contains an example of setting these variables. After setting these variables, the following commands are available:

Now you need to configure the ax25mail-utils program by editing the /etc/ax25/axgetlist.conf file. The following example is to support connecting to PBBSes in example #1 above:

Each remote BBS gets it's own section, unique callsign, and any other specific settings to support the sending and receiving of messages.

NOTE: the associated ax25mail-utils /etc/ax25/axgetmail.conf configuration file NOT currently mentioned in this documentation is only used for remote "FBB" setups. That support is currently not documented yet.

Urgent: Linpac's packet messaging support is still a work in progress so some quirks exist for now:

Now that the basics (and workarounds) are setup, let's fetch any pending messages for you on your configured remote BBS system. Enter in the following command on the Linux prompt (this example is following example #1 above):

NOTE: The above Linux command must be run as the same Unix user that is running the Linpac program.

The axgetlist utility will now fetch an index of all messages on the remote BBS system and store this list in /var/ax25/ulistd/<bbs-name> (all SSIDs are currently stripped). While this Linux command line-based index capture occurs, the packet traffic will NOT show up in Linpac's main send/receive UI as this command is running outside of Linpac. You will see the AX.25 traffic if you have Linpac's AX.25 traffic monitor working. The resulting downloaded index file will then be used to manually download any messages with the getmsg command or interact with those remote messages them via Linpac's :mail interface

8.4 Mail client

This application allows full screen message editing and browsing. It provides a graphical (Ncurses) frontend to mail exchange utilities. The mail client is started by the :MAIL command from Linpac's Channel 0 (aka.. the F1-key view). If you run this command from any other Linpac channel, it won't display any messages!

After the mail interface opens, the H key shows the operating instructions.

In the INCOMING mail folder, you should see a list of messages available to download. Toggle the messages you want to fetch with the SPACEBAR and then use the "d" key to download those messages.

8.5 Logbook

Logbook is a simple application that is started from the cinit.mac and cexit.mac scripts (at the begining and at the end of each connection). It creates the file in the 'log' directory for each callsign and writes there the time when the connections were started and finished and the QRG. The QRG is taken from the QRG field of the station entry in station database. If the station has no QRG defined, the value from the QRG@0 variable is taken.

9 Command line options

LinPac accepts following command line options:

10 Copying

LinPac is Copyright (c) 2002-2020 by David Ranch KI6ZHD and Copyright (c) 1998-2002 by Radek Burget, OK2JBG

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation;

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details (contained in file 'license').

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.


Appendix A - LinPac commands

Built-in commands

a) action commands

External commands

Macros

Commands for creating scripts


Appendix B - Linpac FAQ / Questions and Answers / Getting more help

  1. Q: X doesn't work right in Linpact. Why?
    A: Have you looked in the errors.txt file found in the main LinPac directory? It can provide a lot of clues.
  2. Q: When I start Linpac, I get "Segmentation fault". What is the fix?
    A: You are probably running an old version of Linpac. Please try the newest release version available at https://sourceforge.net/projects/linpac/ or possibly the newest DEVELOP branch. This will most likely require you to compile Linpac to get it running
  3. Q: When I start Linpac, all of the text in the AX.25 monitor is indented to the right. How do I fix this?
    A: Exit Linpac, go into the directory where Linpac is installed, and delete the file:

    Now restart Linpac. Did that solve your issue? No? Also try deleting the files window*.screen and restart Linpac
  4. Q: My question isn't addressed in this document, where else can I get help?
    A: Consider reviewing these other URLS:


Appendix c - Errata

03/30/2020 - dranch

04/01/2019 - dranch


Last update: March 30 2020
Please report any errors to linpac@trinnet.net