Linux is a powerful operating system and offers a great deal of flexibility in how it is configured. With this flexibility comes a cost in configuring it to do what you want. When configuring your Linux machine to accept incoming AX.25 or NetRom connections there are a number of questions you need to ask yourself. The most important of which is: "What do I want users to see when they connect?". As detailed in the HAM-HOWTO there are BBS systems that are being developed that you might want users to see when they connect, alternatively you might want to give users a login prompt so that they can make use of a shell account, or you might even have written your own program, such as a customised database or a game, that you want people to connect to. Whatever you choose, you must tell the AX.25 software about this so that it knows what software to run when it accepts an incoming AX.25 connection.
/usr/local/etc/ax25d.conf
file.This file is the configuration file for the ax25d AX.25 daemon which handles incoming AX.25 and NetRom connections.
The file is a little cryptic looking at first, but you'll soon discover it is very simple in practice, with a small trap for you to be wary of.
The format of the ax25d.conf
file is as follows:
# This is a comment and is ignored by the ax25d program.
[<interface_call>]
<peer1> window T1 T2 T3 N2 <mode> <uid> <cmd> <cmd-name> <arguments>
<peer2> window T1 T2 T3 N2 <mode> <uid> <cmd> <cmd-name> <arguments>
defaults window T1 T2 T3 N2 <mode> <uid> <cmd> <cmd-name> <arguments>
<peer3> window T1 T2 T3 N2 <mode> <uid> <cmd> <cmd-name> <arguments>
...
default window T1 T2 T3 N2 <mode> <uid> <cmd> <cmd-name> <arguments>
Where:
at the start of a line marks a comment and is completely ignored by the ax25d program.
is the AX.25 callsign of the AX.25 or NetRom interface that this particular paragraph is for.
is the callsign of the peer node that this particular configuration applies to. If you don't specify an SSID here then any SSID will match.
is the AX.25 Window parameter (K) or MAXFRAME parameter for this configuration.
is the Frame retransmission (T1) timer in half second units.
is the amount of time the AX.25 software will wait for another incoming frame before preparing a response in 1 second units.
is the amount of time of inactivity before the AX.25 software will disconnect the session in 1 second units.
is the number of consecutive retransmissions that will occur before the connection is closed.
provides a mechanism for determining certain types of general permissions. The modes are enabled or disabled by setting or resetting bits in an 8 bit map. You set that map by setting <mode> to the sum of the following values:
Setup utmp, and run on a ptty (planned).
UNUSED.
UNUSED.
UNUSED.
UNUSED.
UNUSED.
Disallow digipeated uplinks, only allow direct connections.
Lockout, Barred, immediate disconnect.
is the userid that the program to be run to support the connection should be run as.
is the full pathname of the command to be run, with no arguments specified.
is the text that should appear in a ps as the command name running (normally the same as <cmd> except without the directory path information.
are the command line argument to be passed to the <:cmd> when it is run. You pass useful information into these arguments by use of the following tokens:
AX.25 callsign of the connected party without the SSID, in uppercase.
AX.25 callsign of the connected party without the SSID, in lowercase.
AX.25 callsign of the connected party with the SSID, in uppercase.
AX.25 callsign of the connected party with the SSID, in lowercase.
You need one section in the above format for each AX.25 or NetRom interface you want to accept incoming AX.25 or NetRom connections on.
There are two special lines in the paragraph, one starts with the string
`defaults
' and other starts with the string `default
'
(yes there is a difference). These lines serve special functions.
The `default
' lines purpose should be obvious, this line acts as a
catch-all, so that any incoming connection on the <interface_call>
interface that doesn't have a specific rule will match the `default
'
rule. If you don't have a `default
' rule, then any connections not
matching any specific rule will be disconnected immediately without notice.
The `defaults
' line is a little more subtle, and here is the trap
I mentioned earlier. In any of the fields for any definition for a peer you
can use the `*' character to say `use the default value'. The
`default
' line is what sets those default values. The kernel software
itself has some defaults which will be used if you don't specify any. The trap
is that the these defaults apply only to those rules below
the `default
' line not to those above. You may have more than one
`default
' rule per interface definition, and in this way you may
create groups of default configurations.
ax25d.conf
file.Ok, an illustrative example:
# ax25d.conf for VK2KTJ - 21/11/95
# This configuration uses the AX.25 port defined earlier.
[VK2KTJ-1]
NOCALL * * * * * 0 guest /usr/games/fortune
defaults 1 10 * * * 0 root /usr/local/sbin/axspawn axspawn %u +
VK2XLZ-1 * * * * * * * * *
VK2DAY-1 * * * * * * * * *
default 1 10 5 100 5 0 root /usr/local/bin/pms pms -a -o vk2ktj
#
This example says that anybody connecting to the interface on my machine with
the callsign VK2KTJ-1
will have the following rules applied:
Anyone whose callsign is set to `NOCALL' should use the kernel default
parameters and have the fortune program run as guest
for
them.
The defaults
line changes two parameters from the kernel defaults
(Window and T1) and will run the /usr/local/sbin/axspawn program for
them. Any copies of /usr/local/sbin/axspawn run this way will appear
as axspawn in a ps listing for convenience. The next two
lines definitions for two stations who will receive those permissions.
The last line in the paragraph is the `catch all' definition that everybody
else will get (including VK2XLZ and VK2DAY using any other SSID other than -1).
This definition sets all of the parameters implicitly and will cause the
pms program to be run with a command line argument indicating that
it is being run for an AX.25 connection (assuming VK2KTJ-1
to be an
AX.25 interface) and that the owner callsign is VK2KTJ
. (See the
`Configuring the PMS' section below for more details).
If you wanted to define rules for another interface, a NetRom interface for example, then you would add another paragraph coded in the same way with rules and callsign appropriate to it.
This example is a contrived one but I think it illustrates clearly the
important features of the syntax of the configuration file. Jonathon includes
a much longer and more detailed example in the ax25-utils
package that
you should look at if you need more information.
When you have the two configuration files completed you start ax25d with the command:
# /usr/local/sbin/ax25d
When this is run people should be able to make AX.25 connections to your
Linux machine. Remember to put the ax25d
command in your rc
files so that it is started automatically when you reboot each time.
The axspawn program is a simple program that allows AX.25 stations
who connect to be log in to your machine. It is invoked from the ax25d
program as described above. To allow a user to log in to your machine you
should add a line similar to the following into your
/usr/local/etc/ax25d.conf
file:
default * * * * * 1 root /usr/local/sbin/axspawn axspawn %u
If the line ends in the +
character then the connecting user must
hit return before they will be allowed to login. The default is to not wait.
Any individual host configurations that follow this line will have the
axspawn program run when they connect. When axspawn is
run it first checks that the command line argument it is supplied is a legal
callsign, strips the SSID, then it checks that /etc/passwd
file to
see if that user has an account configured. If there is an account, and the
password is either ""
(null) or +
then the user is logged
in, if there is anything in the password field the user is prompted to enter
a password. If there is not an existing account in the /etc/passwd
file then axspawn may be configured to automatically create one.
/usr/local/etc/axspawn.conf
file.You can alter the behaviour of axspawn in various ways by use of
the /usr/local/etc/axspawn.conf
file. This file is formatted as
follows:
# /usr/local/etc/axspawn.conf
#
# allow automatic creation of user accounts
create yes
#
# guest user if above is 'no' or everything else fails. Disable with "no"
guest no
#
# group id or name for autoaccount
group ax25
#
# first user id to use
first_uid 2001
#
# maximum user id
max_uid 3000
#
# where to add the home directory for the new users
home /home/ax25
#
# user shell
shell /bin/bash
#
# bind user id to callsign for outgoing connects.
associate yes
The eight configurable characteristics of axspawn are as follows:
indicates a comment.
if this field is set to yes
then axspawn
will attempt to automatically create a user account for any user who connects
and does not already have an entry in the /etc/passwd
file.
this field names the login name of the account that will
be used for people who connect who do not already have accounts if
create is set to no
. This is usually ax25
or
guest
.
this field names the group name that will be used for any
users who connect and do not already have an entry in the /etc/passwd
file.
this is the number of the first userid that will be automatically created for new users.
this is the maximum number that will be used for the userid of new users.
this is the home (login) directory of new users.
this is the login shell of any new users.
this flag indicates whether outgoing AX.25 connections made by this user after they login will use their own callsign, or your stations callsign.
The pms program is an implementation of a simple personal message
system. It was originally written by Alan Cox. Dave Brown, N2RJT,
<dcb@vectorbd.com>
has taken on further development of it.
At present it is still very simple, supporting only the ability to send
mail to the owner of the system and to obtain some limited system information
but Dave is working to expand its capability to make it more useful.
Configuring the pms program is still a little clumsy at the moment because it is new but bare with it while Dave works on it. The only difficult part is modifying the source code to support your local mail delivery agent and whether you use the ttylinkd program or the talk-ax25 program.
After that is done there are a couple of simple files that you should create
that give users some information about the system and then you need to add
appropriate entries into the ax25d.conf
file so that connected users
are presented with the PMS.
pms.c
If you take a look at the pms.c
file in the ax25-utils
package you will see that there a few items that you can configure.
Perhaps the most important to configure is the one that allows you to specify
what local mail delivery agent you use. In most installations the
deliver program may well work, but in the minimal installation on
my gateway machine I needed to modify the line that previously said:
#define MAIL_DELIVERY_AGENT "deliver %s"to:
#define MAIL_DELIVERY_AGENT "/bin/mail.local %s"
There is no easy way of knowing what local delivery agent your machine is configured to use, so perhaps you could simply look for either of these files in the obvious places and choose whichever seems to be there.
I also have the ttylinkd program installed, so I needed to modify
the section relating to it. I keep my copy of the ttylinkd program in
my /usr/sbin
directory, so I modified the line that previously said:
/* #define MY_TALK "/usr/local/sbin/ttylinkd" */to:
#define MY_TALK "/usr/sbin/ttylinkd"
If you use the talk-ax25 program then you would remove the /*
and */
from around that line instead.
There is one last definition that might be useful to you, and that is if you
have a default email gateway. This line is the line containing the string
MY_GATEWAY
. If you have an email gateway that you use, then you should
remove the comments from this line and change the address to that of your
gateway.
/usr/local/pms/motd
file.The /usr/local/pms/motd
file contains the `message of the day' that
users will be presented with after they connect and receive the usual BBS
id header. The file is a simple text file, any text you include in this file
will be sent to users.
/usr/local/pms/info
file.The /usr/local/pms/info
file is also a simple text file in which
you would put more detailed information about your station or configuration.
This file is presented to users in response to their issuing of the
Info
command from the PMS>
prompt.
When a connected user sends mail to an AX.25 callsign, the pms expects that callsign to be mapped, or associated with a real system user on your machine.
You make this association with the axparms command. An example looks like:
# axparms -assoc vk2ktj terry
This command associates that AX.25 callsign vk2ktj
with the user
terry
on the machine, so any mail for vk2ktj
on the
pms will be sent to terry
.
Remember to put these associations into your rc file so that they are available each time your reboot.
/usr/local/etc/ax25d.conf
file.Adding the pms to your ax25d.conf
file is very simple.
There is one small thing you need to think about though. Dave has added command
line arguments to the PMS to allow it to handle a number of different text
end-of-line conventions. AX.25 and NetRom by convention expect the end-of-line
to be carriage return, linefeed while the standard unix end-of-line is
just newline. So, for example, if you wanted to add an entry that
meant that the default action for a connection received on an AX.25 port is
to start the PMS then you would add a line that looked something like:
default 1 10 5 100 5 0 root /usr/local/bin/pms pms -a -o vk2ktj
This simply runs the pms program, telling it that it is an AX.25
connection it is connected to and that the PMS owner is vk2ktj
.
Check the man page for what you should specify for other connection
methods.
To test the PMS, you can try the following command from the command line:
# /usr/local/bin/pms -u vk2ktj -o vk2ktjSubstitute your own callsign for mine and this will run the pms, telling it that it is to use the unix end-of-line convention, and that user logging in is
vk2ktj
. You can do all the things connected users can.
Additionally you might try getting some other node to connect to you to
confirm that your ax25d.conf
configuration works.