Documentation Index
Alphabetic Index
XRPi Documentation - Configuration
Configuring XRPi
| Prev: Help Windows | Next: Interface Configuration |
(This page is aimed mainly at first-time XRPi sysops. If you are a seasoned XRouter sysop, you probably don't need to read it.)
Contents
1. Main Configuration File
Assuming you have successfully installed and tested XRPi using the dummy configuration, your next job is to edit XROUTER.CFG, which is the main configuration file.
XRPi is supplied with a "dummy" XROUTER.CFG, which is what allowed you to run the program and get a feel for it. The dummy file is deliberately kept simple, to avoid overloading you with information. You may choose to build upon this file, or create your own XROUTER.CFG from scratch, or start with a copy of the example file from the MISC directory.
Whichever option you choose, you are advised to save a copy of the dummy config, because it may one day come in useful when you're trying to track down a problem.
When editing the configuration file, it is better to make incremental changes, testing at each stage, than to try and find a fault when you have changed several things at once.
Firstly, some background information about the general structure of XROUTER.CFG. If you have already read the XROUTER.CFG page, you may skip this section:
XROUTER.CFG is a plain ASCII text file, which can be opened and edited with any text editor. It contains directives of the general form <keyword>=<value>, each on a separate line. (If you do not understand the significance of the <>, please see the conventions section)
Keywords are not case sensitive, and in general they may be specified in any order, but there are exceptions. For example, interfaces MUST be defined before the ports that reference them.
Blank lines are allowed, and comment lines must begin with a semicolon (;) or hash (#) in the leftmost column. Lines must not exceed 255 characters.
The sections of the file outside the INTERFACE, PORT, CONSOLE, APPL and ROUTES blocks, are considered "global", i.e. this is where the keywords with global action can be used. E.g. this is where the node callsign and alias are specified.
Some of the keywords, e.g. IPADDRESS and PACLEN may be used globally (to set defaults) and within PORT definition blocks (to set port-specific overrides).
The absolute minimum configuration must contain NODECALL, NODEALIAS, plus at least one INTERFACE block and one PORT block. For example:
The above would allow XRPi to run without any external hardware, but it wouldn't be very useful. It is merely an example. In order to do any real work, it needs to be fleshed out, as shown in the following sections:
The example config files are largely self-documenting, so you should be able to get up and running fairly easily. But it's always nice to have some instructions, if only for confirmation that you've done everything properly.
This is an overview only. If you want more detail, see the step-by-step section. If you omit a step, you can always come back and perform it later.
The choice of font is left to the sysop, but the recommended font is a "Monospace" one.
To check and set the font, run XRPi, then right click on the display area and select "Preferences".
On the "Style" tab, check it says "Monospace size 10" for "Terminal font". If it does, click "Cancel", otherwise change it and click "OK".
Sizes less than 10 will probably be too small to read clearly, and those over 12 may occupy too much screen area.
Operation with any font other than Monospace is not guaranteed. The height and width of the XRPi display, i.e. the number of screen rows and columns, adjusts to fit the terminal window. However if you change then while the program is running, you may need to restart XRPi to clean up the display.
The minimum height is 25 lines, a legacy of the 80x25 DOS screen which originally constrained XRouter. A taller display is recommended.
The minimum width is 80 columns. If you set it larger, the display will stretch to fit, but the console command line will remain fixed at 80 characters wide. This will be tidied up in a future revision.
XRPi's primary identification for AX25 and NetRom operations is provided by NODECALL and NODEALIAS. You must configure these at least.
You should preferably choose an alias which is geographically relevant beyond your own local area, for example BRSTOL, LEEDS, or BRUM are good, because users can recognise them in node tables.
(Note: All PORTS "inherit" the nodecall and nodealias, but may have additional callsigns, provided by PORTCALL and PORTALIAS within the PORT configuration blocks).
This is the callsign used when you make outgoing connections from any of XRPi's "consoles", and it defaults to NODECALL.
If you wish to use a different callsign for these operations you may override the default using CONSOLECALL. You may at any time override this callsign using the "linked as" command.
If you want the chat server to be visible in other people's NetRom nodes tables, and thus connectible at layer 4, you must add CHATCALL and CHATALIAS. These must be different to NODECALL and NODEALIAS.
The ad-hoc convention is for XRPi chat to use an SSID of -8 for CHATCALL where possible, to distinguish them from non-compatible types. As with nodealias, it is suggested that CHATALIAS should end with "CHT" and begin with something geographically relevant, e.g. BHMCHT for Birmingham, LDSCHT for Leeds etc., so it can be easily identified in node tables.
By default, the chat server's visibility in nodes tables will be the same as XRPi's main nodecall:nodealias. You may wish to limit the visibility of your server to a reasonable geographical area, and discourage chat server "dxing", using a CHATQUAL lower than 255.
If you want to enable XRPi's Personal Mail Server (PMS), you must add PMSCALL at least.
If you want your PMS to be visible on the NetRom network, you must additionally add PMSALIAS and a non-zero PMSQUAL.
If you intend running an APRS IGate (Internet Gateway) whose callsign is different from NODECALL, add APRSCALL.
This callsign is used by the IGate to identify itself in beacons and third party messages. If omitted, it defaults to NODECALL.
If you have an amprnet (44-net) IP address, and wish to connect XRPi into the amprnet, you must add IPADDRESS in the "global" section of XROUTER.CFG.
This address is inherited by all ports, but you may specify additional IP addresses within PORT configuration blocks.
You must additionally configure the IP routing in IPROUTE.SYS. (you may need to disable some TCP ports if there is a conflict with existing apps - enabling IPADDRESS enables TCP operations)
If you have an amprnet host name, add HOSTNAME. If you omit this, it defaults to "NODEALIAS:NODECALL".
2. Minimal Configuration
; Netrom / AX25 Identification
NODECALL=X7XXX
NODEALIAS=XALIAS
; Loopback interface
INTERFACE=1
TYPE=LOOPBACK
MTU=256
ENDINTERFACE
; Port "attached" to interface 1
PORT=1
ID="Loopback port"
INTERFACENUM=1
ENDPORT
Basic Configuration
Don't Panic!
Almost everything is optional...
Provided you configure the callsign and alias, plus a few other
mandatory fields, you'll be up and running in no time. You can "tweak" things later.
3. Quick-start Summary for Impatient People
4. Step by Step Configuration In More Detail
4.a. Display Parameters
Font
Display Height and Width
4.b. Station Identification
Primary Identification
; Netrom / AX25 Identification
NODECALL=G8PZT
NODEALIAS=KIDDER
Console Callsign
CONSOLECALL=G8RAA
Chat Server
; Chat Server Identification
CHATCALL=G8PZT-8
CHATALIAS=KDRCHT
CHATQUAL=100
Personal Mail Server
PMSCALL=G8PZT-2
PMSALIAS=PZTPMS
PMSQUAL=50
APRS IGate
APRSCALL=MB7Uxx
IP Address
IPADDRESS=44.131.91.4
TCP/IP Host Name
HOSTNAME=g8pzt.ampr.org
4.c. Station Location
Location String
If you wish to let people know where your node is (and it's always useful if sysops do this), add QTH. There's no need to be too precise, a town, county and country will suffice. 32 characters maximum.QTH=Kidderminster, Worcs, UK.
Maidenhead Locator
If you wish to specify your Maidenhead locator, add LOCATOR.
Your node will be considered as being in the middle of that square, and this will enable XRPi to calculate distances and directions when it receives APRS position data from other nodes.
You may use either a 6 or 8 character locator. If you wish to define a more precise position, add a suitable position string to IDTEXT (see below).
LOCATOR=IO82VJ
4.d. Texts
Connection Text
If you wish to send a greetings message to callers when they connect, add CTEXT.
The default action (to avoid interfering with BBS connection scripts), is to send this text only for connections to the node alias, and for Telnet connections. You can change this action using CTFLAGS.
There is no limit on the number of lines of text you can specify, but no line must exceed 255 characters. Don't make it too long - remember, your users will see this every time they log on to the nodealias. The end of text is marked by *** on a line by itself.
CTEXT Kidderminster AX25/IP Router. Type ? for list of commands. ***
Info Text
The INFOTEXT is sent to users in response to the plain 'I' command.
Please put something useful or interesting in here. As a user, it is frustrating to type "I" and learn nothing!
INFOTEXT Fourpak Packet Router, Kidderminster, Worcestershire, IO82VJ Sysop: Paula G8PZT @ GB7PZT To connect to the Kidderminster BBS, use the command: C GB7PZT AMPR IP address: 44.131.91.245 To obtain an IP address: Contact G4XJC @ GB7LGS Comments/reports/queries to: G8PZT Information from: G8PZT, G4FPV @ GB7GLO or G0EWH @ GB7PZT ***
ID Text
The IDTEXT is sent on air as an AX25 UI beacon every IDINTERVAL (default 15 minutes). You can use this to advertise the presence of your node.
If the text includes an APRS-format static position code, starting within the first 40 characters, you will be visible on APRS maps and the MHeard function will record distances to heard stations.
The format of the position code is "!ddmm.mmN/dddmm.mmE#" where dd represents degrees of latitude/longitude and mm.mm represents minutes to two decimal places. "N" and "E" may be replaced by "S" and "W" as appropriate.
Note that although you can enter multiple lines of text, only the first line is sent.
The following short example includes a position, town, alias and IP address, allowing anyone who sees the beacon to connect to the system.
IDTEXT !5224.00N/00215.00W# Kidderminster XRPi (KDRMIN) 44.131.91.4 ***
| Prev: Help Windows | Next: Interface Configuration |