XRPi Home

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.)


  1. Main Configuration File
  2. Minimal Config
  3. Quick-start Summary for Impatient People
  4. Step by Step Configuration In More Detail
    1. Display Parameters
      1. Font
      2. Display Height and Width
    2. Station Identification
      1. Primary Identification
      2. Console Callsign
      3. Chat Server
      4. Personal Mail Server
      5. APRS IGate
      6. IP Address
      7. TCP/IP Host Name
    3. Station Location
      1. Location String
      2. Maidenhead Locator
    4. Texts
      1. Connection Text
      2. Info Text
      3. ID Text

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).

2. Minimal Configuration

The absolute minimum configuration must contain NODECALL, NODEALIAS, plus at least one INTERFACE block and one PORT block. For example:

	; Netrom / AX25 Identification

	; Loopback interface

	; Port "attached" to interface 1
		ID="Loopback port"

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:

Basic Configuration

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.

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

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.

  1. Edit NODECALL and NODEALIAS to your own callsigns.

  2. If you want a different callsign for console operations, add CONSOLECALL.

  3. If you want the chat server to be visible and connectible at layer 4, add CHATCALL, CHATALIAS and CHATQUAL.

  4. If you want a PMS, add PMSCALL. If you want it to be visible on NetRom, add PMSALIAS and PMSQUAL.

  5. If you intend to run an APRS IGATE with a different callsign to NODECALL, add APRSCALL.

  6. If you wish to be part of amprnet, add IPADDRESS.

  7. If you have an amprnet hostname, add HOSTNAME

  8. If you want others to know roughly where your node is located, add QTH. You may also add your Maidenhead grid square using LOCATOR.

  9. Customise CTEXT, INFOTEXT and IDTEXT.

  10. Setup the interfacing

  11. If XRPi is supporting applications, configure one or more APPL blocks to alow users to connect to them.

  12. If you aren't running XRPi from a "root" account, you may need to set suitable "capability flags" to make it run.

4. Step by Step Configuration In More Detail

4.a. Display Parameters

  • Font

    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.

  • Display Height and Width

    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.

4.b. Station Identification

  • Primary Identification

    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).

    	; Netrom / AX25 Identification
  • Console Callsign

    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.

  • Chat Server

    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.

    	; Chat Server Identification
  • Personal Mail Server

    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.

  • APRS IGate

    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.

  • IP Address

    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)

  • TCP/IP Host Name

    If you have an amprnet host name, add HOSTNAME. If you omit this, it defaults to "NODEALIAS:NODECALL".


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).


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.

    	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!

    	Fourpak Packet Router, Kidderminster, Worcestershire, IO82VJ
    	Sysop: Paula G8PZT @ GB7PZT
    	To connect to the Kidderminster BBS, use the command: C GB7PZT
    	AMPR IP address:
    	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.

    	!5224.00N/00215.00W# Kidderminster XRPi (KDRMIN)

Prev: Help Windows Next: Interface Configuration