Documentation Index
Alphabetic Index
XRPi Documentation - System Files
XROUTER.CFG
Nearly all of XRPi's configuration is controlled by the mandatory file XROUTER.CFG, which lives in the same directory as XRPi itself. This file is read only when the program starts, but many of the parameters can be changed "on the fly", i.e. while the program is running.
XROUTER.CFG is a plain ASCII text file, which can be opened and edited with Notepad. 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 following link is a heavily commented example xrouter.cfg file.
In the following sections, '*' indicates the mandatory parameters. Additional parameters (e.g. IPADDRESS) may need to be specified to enable full operation. Remaining parameters have sensible defaults built into the program. Defaults are indicated in brackets ().
"Global" Section
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. For example, this is where the node callsign and alias are specified. Other blocks may "inherit" these global values by default.
Some of the keywords, e.g. IPADDRESS and PACLEN may be used both globally (to set defaults) and within PORT definition blocks (to set port-specific overrides).
Configuration Keywords - Overview
Global Keywords
The following keywords are accepted in the GLOBAL section of XROUTER.CFG, and are presented in more detail further down this page:
AGWPORT TCP port for AGWPE emulator (8000)
APPL Begins an application definition block
APPLQUAL Default NetRom quality for applications (150)
APRSCALL Callsign used by Igate
APRSPORT TCP port for APRS server (1448)
BELL Allowed times for console bells (0800-2200)
BLEVEL Leakage level (0-255) for L3EXCLUDE (0)
CHATALIAS Chat server alias
CHATCALL Chat server callsign
CHATLINKS Callsigns of linked chat servers
CHATLOG Controls logging of chat server activity (0)
CHATPORT TCP port for Chat server (3600)
CHATQUAL Chat server Netrom quality to bcast (150)
COMMAND Creates a custom command.
CONSOLE Begins a CONSOLE definition block.
CTEXT Text sent to a users upon connection
CTFLAGS Flags which control sending of CTEXT (9)
CTRLADDR Hex address of hardware control port (378)
DISCARDPORT TCP port for Discard server (9)
DCACHE Size of domain cache (10)
DNS Domain Name Server to use (internal)
DOMAIN Domain suffix (ampr.org.)
DXFLAGS Controls the DX heard display (0)
ECHOPORT TCP port of Echo server (7)
ENABLE_LINKED Controls who may use "*** LINKED AS"
FINGERPORT TCP port of Finger server (79)
FTPPORT TCP port for FTP server (21)
HIDENODES Controls visibility of '#' nodes (0)
HOSTNAME Host name for TCP/IP operations
HTTPPORT TCP port for HTTP server (80)
HTTPROOT HTTP server's root directory (HTTP)
IDINTERVAL Minutes between IDTEXT broadcasts (15)
IDLETIME Idle link shutdown time in secs (900)
IDTEXT ID beacon sent every IDINTERVAL
IGATE Controls whether Igate starts at boot up (0)
INFOTEXT Text sent in response to "I" command
INTERFACE * Begins Interface definition block
IPADDRESS Main (amprnet) IP address (0.0.0.0)
IPENCAP Enable/disable IPENCAP protocol 4 (0)
IPIP Enable/disable IPIP protocol 94 (0)
IPTTL IP Time to live (255)
IPUDPPORT UDP port for rcving IPUDP traffic (94)
L3EXCLUDE Callsigns whose L3 traffic is disrupted
L3TTL NetRom layer 3 Time To Live (25)
L4DELAY NetRom layer 4 delay in secs (3)
L4RETRIES NetRom layer 4 retries (3)
L4TIMEOUT NetRom layer 4 timeout in secs (120)
L4WINDOW NetRom layer 4 window (10)
LOCATOR Maidenhead QTH locator (empty)
LOG Controls activity logging level (0)
MAXARP Max size of ARP table (20)
MAXCIRCUITS Max concurrent NetRom L4 circuits (20)
MAXHOPS Max acceptable hop count (30)
MAXLINKS Max simultaneous AX25 L2 connections (30)
MAXNODES Max size of NetRom nodes table (200)
MAXROUTES Max NetRom neighbour routes (30)
MAXSESSIONS Max simultaneous sessions (20)
MAXTCP Max simultaneous TCP connections (20)
MAXTT Maximum Trip Time in secs (500)
MINQUAL Minimum NetRom quality in nodes table (10)
NODEALIAS * AX25/NetRom alias of this node
NODECALL * AX25/NetRom callsign of this node
NODESINTERVAL Mins between nodes broadcasts (60)
NUMCONOLES Number of consoles (3)
OBSINIT NetRom obsolescence initial value (5)
OBSMIN NetRom obsolescence min to broadcast (3)
PACLEN AX25 default / NetRom packet length (120)
PMSALIAS AX25/NetRom alias of integral PMS
PMSCALL AX25/NetRom callsign of integral PMS
PMSQUAL PMS NetRom quality to broadcast (0)
PORT Begins a port definition block
PROXY Defines a NetRom proxy
QTH Location of this node (empty)
QUALADJUST Derates NetRom quality by callsign (255)
ROUTES Specifies locked-in NetRom routes
RHPPORT Remote Host Protocol server TCP port (9000)
RLOGINPORT TCP port for Rlogin server (513)
ROWS Vertical size of display in rows (25)
SESSLIMIT Max sessions per user (32767)
SOCKSPORT TCP port for SOCKS proxy server (1080)
SORTBYCALL Sort nodes table by callsign not alias (0)
T3 AX25 link check timer in secs (180)
TELNETPORT TCP port for Telnet server (23)
TELPROXYPORT TCP port for Telnet Proxy server (2323)
TTYLINKPORT TCP port for TTYLINK server (87)
UIFLOOD APRS N-n digipeating (WIDE)
UITRACE APRS N-n digipeating (TRACE)
APPL (application) Keywords
The following keywords are accepted in the APPL blocks:
APPLNAME Application name
APPLCALL Application callsign
APPLALIAS Aplication alias
APPLQUAL Application NetRom qulity to broadcast
APPLFLAGS Flags which control application
ENDAPPL * Ends application definition block
See the applications page for more detail of the above keywords.
CONSOLE Keywords
The following keywords are accepted in CONSOLE blocks:
BOTWINBGCOLOR Background for menu bar (cyan)
BOTWINTXTCOLOR Text colour for menu bar (white)
CMDWINBGCOLOR Background color for command line (navy)
CMDWINTXTCOLOR Text colour for command line (yellow)
CONSOLECALL Callsign for console operations
ECHOCOLOR Colour for text echoed from cmd line (yellow)
ENDCONSOLE * Ends console definition block
MIDWINBGCOLOR Background for central window (black)
MIDWINTXTCOLOR Text colour for central window (white)
MMASK Flags specifying protocols to trace (3f8)
MPORTS Ports to monitor by default (all)
REVIEW No. of lines of scrollback (400)
RXCOLOR Text color for RX tracing (lime)
TOPWINBGCOLOR Status line background colour (cyan)
TOPWINTXTCOLOR Status line text colour (white)
TXCOLOR Text colour for TX tracing (pink)
See the CONSOLES page for more detail of the above keywords.
INTERFACE Keywords
The following keywords are used in INTERFACE blocks:
APPLNUM Application number (DEDHOST only)
CHANNEL Channel on multi-channel hardware
CHANNELS No. of TNC channels (DEDHOST only)
COM COM number / Device name
CONFIG Hardware-specfic config options
ENDINTERFACE * Ends interface definition block
ETHADDR Ethernet address (NdisXpkt only)
FLOW Flow control options (async only)
ID Interface identification string
INTNUM Was interrupt number, now multi-purpose
IOADDR Was I/O address, now multi-purpose
KISSOPTIONS Options for KISS interfaces only
MTU * Maximum Transmission Unit
PROTOCOL Protocol used on this interface
SPEED Serial (async) or RF (SCC) baud rate
TYPE * Type of hardware
See the INTERFACES page for more detail of the above keywords.
PORT Keywords
The following keywords are accepted in PORT blocks:
APPLMASK Controls which applications are visible
APRSPATH Default digipeater path for APRS
BCAST List of destinations for "broadcasting"
BCFROM Callsigns who may broadcast
CFLAGS Controls AX25 up/downlinking
CHANNEL Channel to use on interface (A)
CHATALIAS Port override for global chatalias
CHATCALL Port override for global chatcall
CWID Text to send in CW every 30' (SCC only)
DHCP Enables / disables DHCP client (0)
DIGIFLAG Controls digipeating (7)
DIGIPORT Port to digipeat on (this port)
DYNDNS Enable / disable Dynamic DNS update client
ENDPORT * Ends port definition block
EXCLUDE List of callsigns not allowed to connect
FEC Enable / disable Forward Error Correction (0)
FRACK AX25 Frame Acknowledgement time ms (7000)
FULLDUP Allow simultaneous TX/RX (SCC only)
ID * Text to identify port on ports display
IDPATH Dest & digi path for ID beacons ("ID")
IDTEXT Port override for global IDTEXT
INITSTR Modem initialisation string (modem only)
INTERFACENUM * Interface number this port is bound to
INTERLOCK Prevents simultaneous TX on SCC cards
IPADDRESS Port override for global IP address
IPLINK IP address / hostname of AXIP/AXUDP peer
MAXFRAME Max outstanding AX25 L2 frames (3)
MAXHOPS Port override for global MAXHOPS
MAXTT Port override for global MAXTT
MHEARD Enable / disable MHeard on this port
MHFLAGS Controls contents of MHeard list (255)
MINQUAL Port override for global MINQUAL
MINTXQUAL Min NetRom quality to broadcast
NETMASK Subnet mask used with IPADDRESS
NODESINTERVAL Port override for global NODESINTERVAL
PACLEN Port override for global PACLEN
PERSIST Probability to transmit 0-255 (64)
PIPE Creates a "frame pipe" to another port
PIPEFLAG Controls frame piping (3)
PMSALIAS Port override for global PMSALIAS
PMSCALL Port override for global PMSCALL
PORTALIAS Port override for global NODEALIAS
PORTALIAS2 Secondary alias for digipeating only.
PORTCALL Port override for global NODECALL
PROXY NetRom systems to tunnel AX25 to
QUALITY Default NetRom neighbour quality (10)
RESPTIME AX25 delayed ack timer in ms (2000)
RETRIES Max connect/disconnect/resent attempts (10)
RFBAUDS RF baud rate (1200)
SESSLIMIT Max simultaneous connections per user (255)
SLOTTIME CSMA interval timer (millisecs) (100)
SOFTDCD Use software DCD (SCC only) (0)
SYSOP If 1, all users on this port are sysops (0)
TXDELAY Delay (ms) between PTT and start of data (300)
TXPORT Port on which to TX if not this one (0)
TXTAIL Delay (ms) between data end and PTT drop (100)
UDPLOCAL RX UDP port for AXUDP operations (93)
UDPREMOTE TX UDP port / Partners AXUDP RX port (93)
UNPROTO Dest & digi calls for unproto broadcasts
USERS Max simultaneous users on this port (255)
VALIDCALLS Only these callsigns allowed to connect.
See the PORTS page for more detail of the above keywords.
Global Keywords - Detail
AGWPORT
TCP port for XRPi's AGW Packet Engine (AGWPE) emulator.
This is the port on which the emulator accepts connections from AGWHOST clients (applications). It defaults to 8000, which is AGW's default host port, and therefore the port most applications expect. You may need to move or disable it if you are running "real" AGWPE or the AGW Interface on the same PC.
Example: AGWPORT=8001
See the TCP-PORTS page for details of how to configure this port.
APPL
Begins an application definition block, and specifies the "application number".
Historically this number had to match the BPQ application type, but as XRPi does not currently support BPQ applications, you may use any number between 1 and 8, providing no two APPL blocks use the same number. See the applications page for more information about application blocks.
Example: APPL=7
APPLQUAL
Default NetRom quality to broadcast for applications (0-255).
This value is inherited by all applications, unless overriden by an APPLQUAL within an APPL block. The default is 150.
Example: APPLQUAL=80
APRSCALL
Callsign used by the IGATE to identify itself in beacons and third party messages.
If omitted, it defaults to NODECALL.
Example: APRSCALL=MB7UXX
APRSPORT
TCP port for APRS server (default=1448)
The APRS server allows APRS applications such as UI-view to use XRPi to access all the APRS data handled by XRPi.
See the TCP-PORTS page for details of how to configure this port.
BELL
Sets the hours during which the console bells are allowed to sound.
These are the two tone connection (low->high) and disconnection (high->low) bells, the 4 tone (Star Trek doorbell) sysop paging sound, and the various bells associated with sysop chat. Console bells use the PC speaker, not the soundcard. The default bell times are 08:00 to 22:59 inclusive.
Times may be supplied either as a series of single hours, or in one or more ranges of times e.g. "8-22", or as combinations of the two. The setting may be altered at any time using the BELL command.
Whatever the BELL setting, the console may still bleep if the sysop tries to exceed a line length or delete back beyond the start of a line.
Example: BELL=0-5,11-23
BLEVEL
Leakage level (0-255) for L3EXCLUDE (default=0).
This allows you to "choke" traffic from troublesome users to a greater or lesser degree. This has been found to be a more effective means of control than blocking them outright, which just shifts the troublemaker to another route. A miscreant being managed by this method usually assumes the network is slow, and doesn't realise his activities are being controlled.
A BLEVEL of 0 prevents ALL L3 packets from the budlisted stations, and at the other extreme 255 will allow all packets. For example 64 will allow on average 1 in 4 L3 packets, which should slow things down a bit!! The sysop can vary this parameter on the fly.
Example: BLEVEL=0
CHATALIAS
AX25/Netrom "alias" for chat server (6 chars max).
This parameter is mandatory if you wish the chat server to be available via NetRom or to link with other servers. If you make CHATALIAS the same as NODEALIAS, the chat server will not be directly connectible (i.e. it will only be available using the CHAT command).
It is suggested this 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.
Example: CHATALIAS=KDRCHT
CHATCALL
AX25/Netrom callsign for the chat server.
This may be the same as the NODECALL, but must use a different SSID, otherwise the chat server will not be directly connectible. The ad-hoc convention is to use an SSID of -8 for XRchat callsigns where possible, to distinguish them from non-compatible types.
The chat server is an integral part of the system and cannot be completely disabled. You may prevent it from being directly connectible by setting CHATCALL and CHATALIAS the same as NODECALL and NODEALIAS, but it will still be available to all users via the CHAT command.
Example: CHATCALL=G8PZT-8
CHATLINKS
List of peer chat servers to which our chat server will link.
For NetRom links you must supply the *callsigns* not the aliases. You may use multiple CHATLINKS lines, or put several callsigns in a single line, separated by commas.
Unilateral links are not allowed - each partner in this list must place your CHATCALL in their CHATLINKS list. You may only use partners who are in your node tables.
At present, links to RoundTable/BPQ peers must use Netrom, and links to Ping-Pong peers must use TCP/IP. Links with XRouter/XRPi peers may use either NetRom or TCP, although NetRom is the norm.
Don't link with distant servers - if the links are too slow , frames will be dumped and your users will get poor service. You may disable all outgoing and incoming linking by omitting this keyword.
Links with XRouter chat peers are specified thus:
CHATLINKS=<netrom_call>,<netrom_call>,... CHATLINKS=<ipaddress:tcpport> <callsign>
Links with Tampa Ping-Pong converse servers are specified as follows, with the peername prefixed with a "*":
CHATLINKS=<ip_address:tcp_port> *<peername>
For links with RoundTable/BPQ chat servers the callsign must be prefixed with a '+' e.g. "+XE1FH-11".
Examples:
CHATLINKS=G9XOT-8,+VK1CHT,G7DTY-8 CHATLINKS=80.185.22.37:3601 *brmcht
The sysop may also add and delete links at any time using the "/LINKS" command in the chat server.
CHATLOG
Chat server Activity Logging level ( default=0).
Add together the values corresponding to the desired options from this table:
1 Local user connect / disconnect event 2 Remote user connect / disconnect event 4 Peer server connect / disconnect event 8 Local channels 1-255 join / leave events 16 Public channel join / leave events 32 Log channel notifications 64 Log the text of conversations 128 Use a single logfile, instead of daily ones
CHATPORT
TCP port for chat server (default=3600).
This is the TCP port for connecting directly to the chat server without connecting first to the node and issuing the CHAT command. The ports for Linux and XRPi TCP/IP stacks may be specified independently, and either one may be moved or disabled.
See the TCP-PORTS page for details of how to configure this port.
CHATQUAL
Chat server Netrom quality to broadcast.
This can be used to limit the NetRom visibility of your server to a sensible geographical area, and discourage chat server "dxing". The default is 255, i.e. the chat server is visible over same distance as NODECALL. The value is only meaningful if BOTH CHATCALL and CHATALIAS are defined, otherwise nothing is broadcast. You must allow your chat server to be visible as a netrom node if you wish to link it with other servers.
Example: CHATQUAL=150
COMMAND
Creates a custom command.
This allows you to define single-word aliases for frequently used command strings. For example you might wish to create BBS, CONV and DXCLUSTER commands to point to local systems. There is no limit to the number of commands you can define.
Each command is defined using a separate "COMMAND=" string, and the arguments are <alias> <real_cmd>. e.g. "COMMAND=BBS C 7 GB7PZT" means "create a new command called BBS, which translates to the sequence C 7 GB7PZT"
Examples:
COMMAND=BBS C 1 GB7PZT COMMAND=CONV TELNET 44.131.90.1 3600 COMMAND=DXCLUSTER C GB7DXC
CONSOLE
Begins a CONSOLE definition block.
The default console settings may be modified using suitable directives in the global section. These settings may in turn be be overridden on a per-console basis by using optional CONSOLE definition blocks. Only those values which differ from the defaults need be specified. Alternatively you may omit the globals and fully specify each console. Consoles are numbered from 1 to 5.
Console definition blocks start with CONSOLE=n where n is a number between 1 and 5, and end with ENDCONSOLE. They may contain any or all of the keywords listed here. There should be one block for each console that differs from the default settings.
For example:
CONSOLE=3 MIDWINBGCOLOR=NAVY MIDWINTXTCOLOR=WHITE CMDWINBGCOLOR=GREEN CONSOLECALL=G8PZT-4 MMASK=1f ; AX25/Netrom only MPORTS=1-2 ; Monitor ports 1 and 2 only ENDCONSOLE
CTEXT
Text sent to users upon connection
By default, this "Connection text", is sent to callers who connect to the NODEALIAS, but not to callers who connect to the NODECALL. The CTFLAGS directive controls which callers receive the text.
When a user connects to an unknown node, he usually likes to know (a) where the node is, (b) what sort of software it is running, and (c) how to get help with commands. But he doesn't want to wait for a long rambling text every time he connects, so please keep the text brief but informative. The end of text is marked by a line beginning with ***
Example:
CTEXT MyTown AX25/IP Router Type ? for list of commands. ***
CTFLAGS
Flags which control which callers receive CTEXT.
The argument is formed by adding together the decimal values corresponding to the desired option(s) from the following list:
1 - Send ctext if connect is to Node/port alias 2 - Send ctext if call is to Node/port call 4 - Send ctext on L4 connects. 8 - Send ctext to TCP (TELNET) callers.
The default is 9 (Alias and TCP only).
Example: CTFLAGS=1
CTRLADDR
Hex address of hardware control port (default=378).
In DOS XRouter, this was the address (in hexadecimal) of the parallel port (if any) used for controlling / monitoring up to 8 external hardware devices. It is not yet functional in XRPi.
Example: CTRL=358
DCACHE
Maximum entries in domain cache (default=10).
The domain cache is used during hostname to IP address resolution. This directive is a hang-over from the days when the XRouter program and all its data had to fit into 640kb DOS memory! You may set it much larger on XRPi, although a very large cache is probably counter-productive. Set it large enough to accommodate all the hostnames used by your AX*P links.
Example: DCACHE=20
DISCARDPORT
TCP port (service number) for DISCARD server (default=9).
This is a "sink" server that dumps anything that is sent to it, which is useful for testing. It is recommended that you enable it on the XRPi IP stack (i.e. for amprnet use), but disable it on Linux's stack, as shown in the following:
Example: DISCARDPORT=9 0
To use the DISCARD server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
DNS
Domain Name Server to use (default=internal).
This specifies the IP address(es) of "upstream" Domain Name Server(s), which are to be consulted during the process of hostname to IP address resolution. It is only required if you don't wish to use the Linux resolver.
Syntax: DNS=<ipaddr> [domain]
If [domain] is specified, that name server will only be used to resolve hostnames in that domain, and the hostnames in that domain will only be resolved using that server and no others.
For example: "DNS=44.131.91.245 .ampr.org." tells XRPi to exclusively use the server 44.131.91.245 to resolve all ampr.org hostnames. That server will not be used to resolve hosts outside the ampr.org domain, and ampr.org will not be resolved using any other server.
The [domain] argument may be specified with or without a trailing dot. e.g. ".ampr.org" or ".ampr.org."
You may specify more than one DNS by including more than one DNS directive. If you don't specify any servers, domain resolution will use the services provided by Linux. If neither XRPi nor Linux has any connectivity to a suitable DNS, the only way to resolve addresses is to use manual entries in DOMAIN.SYS.
Example: DNS=62.31.176.115
DOMAIN
Domain suffix (default=ampr.org.)
The domain suffix is automatically appended to any hostname that is entered without any dots (periods) in it. For example if you type "telnet g8pzt", XRPi extends it to "g8pzt.ampr.org." prior to resolving the hostname to an IP address (note that the the trailing dot is important). However, if you enter a complete hostname such as "www.fred.com", XRPi does not extend it.
This directive was provided to enable XRouter to operate in networks other than amprnet, for example in CB packet networks, where the domain suffix would be something like "nl.cbpr.org."
Example: DOMAIN=nl.cbpr.org.
DXFLAGS
Optional flags to control the DX heard display (default=0).
The argument is formed by adding together the decimal values corresponding to the desired option(s) from the following list:
Bit Value 0 0 - Record directly heard stations only 0 1 - Record digipeated and direct stations 1 2 - Enable logging of DX exceeding specified distance. 2 4 - Log frame contents of qualifying DX.
If DX logging is enabled (by setting bit 2), any received APRS positions which exceed the threshold distance are logged to LOG\DXLOG.TXT. Bits 3 - 14 specify the minimum distance which will be logged, from 4Km to 32764Km in 8Km steps, e.g. DXFLAGS=502 enables DX logging, with a threshold of 500Km. If logging is not enabled, bits 3-14 are ignored.
Example: DXFLAGS=102 ; enable dx logging, direct only, threshold 100km
ECHOPORT
TCP "port" (service number) of ECHO server (default=7).
This server echoes anything it receives back to the sender, which is useful for testing. It is recommended that you enable it on the XRPi IP stack (i.e. for amprnet use), but disable it on the Linux stack, as shown below:
Example: ECHOPORT=7 0
To use the ECHO server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
ENABLE_LINKED
Controls who may use the "*** LINKED AS" command. The default is "N", and the possible values are:
Y - Command is unrestricted. A - Only applications may use the command. N - No-one may use the command.
Example: ENABLE_LINKED=A
FINGERPORT
TCP port (service number) of Finger server (default=79).
This server retrieves files from the FINGER directory and allows users to "put a finger on" (i.e. find information about) other users.
It is recommended that you enable it on the XRPi IP stack (i.e. for amprnet use), but disable it on Linux's stack, as shown in the following:
Example: FINGERPORT=79 0
To use the finger server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
FTPPORT
TCP port (service number) for FTP server (default=21).
The FTP server allows remote sysops to upload, download, list, rename and delete files, create and remove directories etc. It is for use by sysops only.
Example: FTPPORT=21 10021
To use the FTP server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
HIDENODES
Controls visibility of '#' nodes (default=0).
If HIDENODES is set to 1, nodes whose alias begins with "#"are not displayed by the normal N command. However, whatever the setting, they can always be displayed using "N *".
Example: HIDENODES=1
HOSTNAME
Optional host name for TCP/IP operations. If you omit this, it defaults to "NODEALIAS:NODECALL".
Example: HOSTNAME=g8pzt.ampr.org
HTTPPORT
TCP port (service number) for HTTP server (default=80).
This server retrieves files from within a directory tree specified by HTTPROOT, and runs basic commands.
Example: HTTPPORT=80 10080
To use the HTTP server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
HTTPROOT
Root directory for the HTTP server (default=HTTP).
This allows the HTML files to be located somewhere more convenient, even on another drive if required.
If you omit this directive, the default will be a directory called "HTTP" within the XRPi working directory.
If the directory doesn't exist, the server will not work.
For security reasons it is important that you don't use the XRPi working directory as the HTTP root!
Example: HTTPROOT=D:\WEB
IDINTERVAL
Minutes between ID broadcasts (default=15).
This is the time interval between broadcasts of IDTEXT on each port. A setting of 0 disables ID beacons.
Example: IDINTERVAL=20
IDLETIME
Idle link shutdown timer in secs (default=900).
AX25 L2 Links with neighbour nodes are closed down if they haven't exchanged any L3 traffic for this amount of time. This is an outdated idea and shouldn't come into play these days, as the links are periodically probed by L3RTT measurements.
Example: IDLETIME=600
IDTEXT
One-line ID beacon, broadcast every IDINTERVAL.
If your APRS-format static position code is included, 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 is "!ddmm.mmN/dddmm.mmE" where dd represents degrees of latitude or longitude and mm.mm represents minutes to two decimal places. "N" and "E" may be replaced by "S" and "W" as appropriate.
Example:
IDTEXT !5824.22N/00515.00W MyTown Router (DUMMY), 44.128.128.128 ***
IGATE
Controls whether or not the APRS Packet<>internet gateway (Igate) is started at boot-up.
A zero value (default) doesn't start the igate (but it can be started anytime using the "start igate" command), and a non-zero value starts it immediately.
Leave this commented out, or set to zero if you aren't running an APRS Internet gateway.
Example: IGATE=1 ; Start Igate at boot up
INFOTEXT
Text sent in response to "I(nfo)" command.
This should give as much useful information as possible, as concisely as possible. Imagine yourself as a user who has reached your node from afar, then provide the sort of information that you would like to know in that situation. The end of text is marked by a line beginning with ***
Example:
INFOTEXT XRPi Packet Router, MyTown, UK, IO99ZE Sysop: Roger G9DUM @ GB7PZT (g9dum@hotmail.com) To connect to the Dummy BBS, use the command: C GB7DUM AMPR IP address: 44.128.128.128 Comments/reports/queries to: G9DUM Website: www.g9dum.com/node ***
INTERFACE *
Begins an INTERFACE definition block. The argument is a number between 1 and 255 which identifies the interface in subsequent PORT blocks. You must define at least one interface, otherwise XRPi will not start.
Example: INTERFACE=2
IPADDRESS
Core IP address for amprnet (44-net) IP routing (default=0.0.0.0).
If you don't already have an amprnet address, you may obtain one from your local amprnet IP co-ordinator.
If you don't wish to route IP, comment this out or set it to 0.0.0.0.
This IP address is "inherited" by all ports, but you may optionally specify an additional address in each PORT block.
Example: IPADDRESS=44.128.0.1
IPENCAP
Enable IPENCAP encapsulation (protocol 4) via Linux IP stack (default=0)
You only need this if you expect to receive IP-within-IP protocol 4 datagrams from other systems via the Linux stack. IPENCAP via XRPi's own stack is not affected by this directive. See IP-STACKS for more details of the IP stacks available to XRPi.
IPENCAP has largely replaced IPIP (protocol 94), but has the disadvantage that it is blocked by MS-Windows systems.
This feature needs XRPi to be run from an account with root privileges, OR to have the CAP_NET_RAW capability flag set.
Example: IPENCAP=1
IPIP
Enable IPIP encapsulation (protocol 94) via Linux IP stack (default=0)
You only need this if you expect to receive IPIP encapsulated datagrams from other systems via the Linux stack. IPIP via XRPi's own stack is not affected by this directive. See IP-STACKS for more details of the IP stacks available to XRPi.
Protocol 94 was the original encapsulation protocol, and unlike IPENCAP is not blocked by MS-Windows.
This feature needs XRPi to be run from an account with root privileges, OR to have the CAP_NET_RAW capability flag set.
Example: IPIP=1
IPTTL
IP "Time To Live" (TTL) (default=255).
This is the maximum number of router to router "hops" an IP datagram is allowed to make. A low value ensures that datagrams stuck in "routing loops" will die quickly, but be aware that Internet-routed packets may easily make 20 or 30 hops, so don't set it too low. Ignore this if you haven't enabled IP routing.
Example: IPTTL=50
IPUDPPORT
UDP port for IPUDP (IP over UDP) encapsulation (default=94).
Use this to reassign the port if another application is using port 94.
You will need to reassign the port to a number above 1023 if XRPi is not running from a root account and does not have the CAP_NET_BIND_SERVICE capability flag set.
Example: IPUDPPORT=9494
L3EXCLUDE
List of callsigns from whom L3 traffic will not be accepted.
This should be used only in exceptional circumstances!
Depending on the BLEVEL setting, L3 traffic from callsigns in this list will either be disrupted (by randomly dropping packets to cause L4 retries) or blocked altogether.
Callsigns should be seperated by commas.
Example: L3EXCLUDE=N3UOO-5
L3TTL
Maximum NetRom layer 3 hops (Time To Live) (default=25).
This specifies a limit to the number of nodes a Netrom L3 packet may traverse before it is dumped, and is used to prevent packets from looping forever in routing loops.
Example: L3TTL=15
L4DELAY
NetRom layer 4 delay in seconds (default=3).
No. of seconds to delay a L4 ack in case further frames arrive.
10 secs is probably OK on normal AX25 RF links, but is excessive on wire links, leading to a slow throughpuit. However, XRPi will attempt to adjust this value to cope with prevailing conditions.
Example: L4DELAY=10
L4RETRIES
NetRom layer 4 retries (default=3). This is the number of L4 connect/disconnect or retransmission attempts allowed before the link is abandoned.
L4TIMEOUT
NetRom layer 4 timeout in seconds (default=120)
Specifies the number of seconds between L4 retries and L4 connect/disconnect attempts. 120 secs is OK for a radio-based network, but is excessive for an Internet-based one. You may have to compromise, but don't set it too low.
L4WINDOW
NetRom layer 4 window (default=10)
Specifies the number of unacked L4 frames allowed before XRPi stops to await an ack. The default is OK for wire links, but a value of 4 is more normal for radio links.
LOCATOR
- Maidenhead QTH locator (no default).
This is your 6 or 8 character Maidenhead QTH locator, e.g. "LOCATOR=IO82DJ". It is an easier but less accurate means of specifying XRPi's position for APRS purposes.
LOG
Controls activity logging level (default=0)
Setting LOG=1 will log all connects, disconnects, user-entered commands and chat server activity. LOG=0 disables this function. Can be overridden by the LOG command at any time.
MAXARP
Maximum no. of entries in Address Resolution Protocol (ARP) table (default=20).
The ARP table stores the "hardware" (e.g. Ethernet or AX25) and IP addresses of the immediately neighbouring IP routers. This allows the IP datagrams to be "wrapped" in Ethernet or AX25 frames for transmission to neighbours.
As the amount of memory available to DOS XRouter was very small, the MAXARP command allowed sysops to control the amount of memory that would be used by ARP. Memory is not an issue with XRPi, but you are unlikely to need a large ARP table unless you have a very large LAN.
MAXCIRCUITS
Maximum number of concurrent NetRom L4 circuits (default=20)
This was another means for DOS XRouter sysops to control the amount of memory used. Pre-allocating memory for circuits also prevented dynamic allocation failures. You may set this much higher in XRPi if required.
MAXHOPS
Max acceptable hop count (default=30).
Defines the maximum "hop count" for new nodes table entries received via INP3 unicasts from neighbours. Node information with hop counts that exceed this figure are not accepted into the nodes table.
This value is inherited by all PORTS, and all ROUTES learned via those ports unless overridden by a MAXHOPS entry in the PORT or ROUTE definition.
MAXLINKS
Maximum simultaneous AX25 L2 links (default=30).
You should set this large enough to accommodate the total number of AX25 L2 users and internode links that you expect.
MAXNODES
Maximum size of NetRom nodes table (default=200).
If you have a large nodes table, the output from the "N" command may be too much for an RF channel to handle. On the other hand, if the table size is to small for the number of nodes, nodes will keep disappearing from the table as their slots are reallocated to "fresher" entries.
You should decide what table size is appropriate for your circumstances, set a MAXNODES large enough to accommodate the expected nodes, and use QUALITY and MINQUAL to control the no. of nodes in the table.
MAXROUTES
Maximum simultaneous NetRom neighbour routes (default=30).
You should set this equal to or greater than the expected number of direct NetRom neighbour nodes.
MAXSESSIONS
Maximum simultaneous sessions (default=20).
The purpose of this was to save memory in XR16, rather than to limit the number of sessions. Memory is not an issue in XRPi, but you may have other reasons for limiting the mumber of sessions, so the directive has been retained.
MAXTCP
Maximum simultaneous TCP connections (default=20).
This was another resource management tool, more relevant in XR16 than XRPi.
MAXTT
Maximum Trip Time in 1/100ths of s second (default=5000).
Specifies the maximum accepted "trip time" (transit time) for new nodes table entries received via INP3 unicasts from neighbours. Node information with trip times that exceed this figure are not accepted into the nodes table.
This value is inherited by all PORTS, and all ROUTES learned via those ports unless overridden by a MAXTT entry in the PORT or ROUTE.
The default value is 5000 (50 seconds), and the maximum is 60000 (600.00 seconds). Trip times of 600 seconds are considered "unreachable".
MINQUAL
Minimum NetRom quality to add to node table (default=10).
The "quality" parameter of each node entry received in a NetRom nodes broadcast is "de-rated" according the the formula Q = ((Q * RQ) + 128) / 256, where "Q" represents quality and "RQ" is the "route quality" to the neighbour making the broadcast. The de-rated quality is then compared to MINQUAL. If the new quality is greater or equal to MINQUAL, the route to that node is entered into the table, otherwise it is ignored.
This is the global value which is inherited by all PORTs unless overridden by a port MINQUAL directive.
NODEALIAS *
AX25/NetRom alias of this node.
Up to 6 alphanumeric characters, with no SSID. Aliases beginning with "#" are not displayed in node lists, and are used for "linking only" nodes with no user access.
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.
NODECALL *
AX25/NetRom callsign of this node.
Up to 6 chars plus optional SSID between 1 and 15. This is the callsign used for all L3/4 operations, and the default for L2 operations on each port.
NODESINTERVAL
Mins between nodes broadcasts (default=60).
This value is inherited by all ports, but may be overridden on a per-port basis by including NODESINTERVAL within a PORT configuration block. A value of 0 disables nodes broadcasts.
The optimum values for OBSINIT and OBSMIN depend on NODESINTERVAL, thus you might need to adjust them if you adjust the interval, to prevent your neighbour nodes from going "obsolete".
NUMCONOLES
Number of consoles (default=3).
You may have up to 5 "virtual" consoles, upon which the sysop may conduct independent sessions. Consoles are selected by the left and right arrow keys, or by use of the Alt-W drop down menu option.
OBSINIT
NetRom obsolescence initial value (default=5).
An obsolescence counter is maintained for every neighbour in the NetRom routes table, and is reset to the OBSINIT value whenever a nodes broadcast is heard from the neighbour.
Together with OBSMIN this determines how long the routes and nodes stay in the table after they are last heard about. With the default values this will be between 2 and 3 hours.
OBSMIN
- NetRom obsolescence minimum to broadcast (default=3)
The obsolescence count (see OBSINIT above) for each NetRom neighbour is decremented every NODESINTERVAL. If it drops below OBSMIN, the route is considered obsolete, and nodes learned via that neighbour are no longer included in nodes broadcasts.
If your NODESINTERVAL is shorter than your neighbours', your obsolescence count will decrement more than once between each received nodes broadcast, in which case you may need to set OBSMIN lower or OBSINIT higher, to prevent the neighbours from going obsolete.
PACLEN
AX25 default / NetRom packet length (default=120).
Sets global default Paclen, i.e. the maximum length of the information-bearing portion of an AX25 packet.
The maximum is 256, and default is 120. This may be overridden on a port by port basis by PORT paclens. It may also be changed at any time, ising the PACLEN command.
The choice of paclen depends on many factors such as the link data rate, transmission and addressing overheads, link contention and error rate etc.
Small packets are less likely to be corrupted by errors or QRM, but are inefficient when addressing or transmission overheads (e.g. txdelay) are large. Big packets are more efficient, but are more likely to be lost if the link has errors or QRM, and the re-transmissions will take longer.
PMSALIAS
AX25/NetRom alias of integral PMS.
Up to 6 alphanumeric characters, with no SSID. This alias is required if the PMS is to be visible via NetRom. It must not be the same as any other alias or callsign used by XRPi.
Example: PMSALIAS=PZTPMS
PMSCALL
AX25/NetRom callsign of integral PMS.
This is required if the PMS is to be connectible via AX25 or NetRom. If you don't specify a PMSCALL, the PMS is disabled.
It must not be the same as any other callsign or alias used on the system. The callsign may be the same as NODECALL, or it may be different (e.g. your own callsign). If you use the NODECALL, you must use a different SSID. A long standing convention is to use -2 as the SSID for personal mail systems.
Example: PMSCALL=G8PZT-2
PMSQUAL
PMS quality to include in Netrom nodes broadcast (0-255).
The default is 0, i.e. no broadcast. A non-zero value is only valid if both PMSCALL and PMSALIAS are defined, otherwise it is ignored.
Before setting a non-zero value, think carefully about whether or not your PMS needs a NetRom presence of its own. Does it really need to be visible in everyone's nodes list, or would it just cause unnecessary clutter?
If you do decide to give the PMS a NetRom presence, for example if you are running it as a public mailbox, you can restrict its spread by setting a relatively low quality.
Example: PMSQUAL=50
PORT
Begins a PORT definition block. The argument is the port number, which must be between 1 and 32767 and not used by any other port. The block ends with ENDPORT, and everything between these keywords is treated as a port directive, instead of a global one.
Example: PORT=3
PROXY
Defines a NetRom to AX25, or a NetRom to TCP "proxy" translation.
These are used to give AX25-only and TCP-only systems a NetRom presence. See the PROXIES page for a detailed explanation.
QTH
Location of the node (default=blank)
This specifies (in words) where the node is located, because it's the sort of thing that node-hoppers like to know. You don't have to be too specific - town, region and country are sufficient.
Example: QTH=Droylesden, Manchester, England.
QUALADJUST
Adjusts NetRom quality by callsign (default=255).
This allows you to de-rate the NetRom quality of a node or group of nodes based on the NetRom callsign, instead of the route on which they were received. Thus you can change the relative qualities to favour your local nodes, or (more likely) those which share your language.
This feature is experimental, and should only be used if the need arises. Note that this only works on netrom "quality", as nodes which are learned via INP3 have no quality to de-rate.
The "default" argument sets the default value which is used to de-rate all nodes not matched by any other QUALADJUST statement. The normal NetRom de-rate algorithm is used, so 255 gives no de-rate and 0 gives full de-rate (i.e. to block a callsign or group of callsigns). If there are no QUALADJUST statements the default is 255.
See the QUALADJUST page for more information.
Example:
QUALADJUST=default 180 QUALADJUST=G* 255 QUALADJUST=M* 255 QUALADJUST=2* 255
ROUTES
Starts a ROUTES block, which specifies locked-in NetRom routes.
The block begins with ROUTES and ends with ***. Syntax of each entry in the block is as follows:
[! [maxframe [frack [paclen]]]] You must specify at least callsign, port and quality.
If you include the lock flag ( ! ) the route will be "locked in", and can only be changed by a replacement entry with the lock flag set. If you don't include the lock flag, the route will eventually expire if not confirmed by the reception of nodes broadcasts. In either case, if the file XRNODES is present, its contents will override the entries here, subject to the locking rules above. The sysop may also edit routes while XRouter is running, using the ROUTES command.
Maxframe, frack and paclen are optional. If specified they override port defaults for that route. Note FRACK is expressed in milliseconds, e.g. 7000 = 7 secs. Maxframe > 7 will allow Modulo-128 to be attempted on that route.
Example:
ROUTES ; Lock in g6yak on port 1 with quality 100 and maxframe 32 :- g6yak 1 100 ! 32 ***
RHPPORT
Remote Host Protocol server TCP port (default=9000)
There are currently no publicly available RHP applications, so you may disable this.
See the TCP-PORTS page for details of how to configure this port.
RLOGINPORT
TCP port for Rlogin (Remote Login) server (default=513)
This is a telnet server for sysop access only, password protected by entries in PASSWORD.SYS.
To use RLogin on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
ROWS
Height of display window in rows of text (default=25).
25 rows is the default (identical to the DOS version), which allows XRPi to run in full-screen mode if desired.
You should be able to extend the height to at least 40 rows. Some machines will allow 50 or 60 rows. Setting this value too high will cause the display to break up and jump around within a window which has scroll-bars (if set correctly, there should be no scroll bars)
SESSLIMIT
Max sessions per user (default=unrestricted)
Overall limit on the number of of concurrent sessions per user, across all ports. This might be useful for restricting "troublesome" users!
SOCKSPORT
TCP port for SOCKS proxy server (default=1080).
To use the socks proxy on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
SORTBYCALL
Sort nodes table by callsign instead of alias (default=0).
By default, the plain "N" command lists nodes in ALIAS order. Although the "N C" command can be used to display nodes in CALLSIGN order, some sysops prefer this to be the default. Setting SORTBYCALL to 1 forces the "N" command to display the nodes in callsign order.
T3
AX25 "T3" (Link check) timer in seconds (default=180).
AX25 L2 links that are apparently open, but have been idle for this length of time are probed to verify that they are still alive. If no response is received, the link is closed.
TELNETPORT
- TCP port for Telnet server (default=23).
The telnet server allows command-mode connections to the node via TCP/IP. The sysop may choose which IP source address ranges may connect, whether or not callsign validation and/or passwords are required, and whether guest (read only) access is allowed, using suitable access control entries in ACCESS.SYS and IPROUTE.SYS. If passwords are required, they are stored in USERPASS.SYS.
To use the Telnet server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
TELPROXYPORT
TCP port for Telnet Proxy server (default=2323).
This server allows TCP/IP applications to make full-binary connections with NetRom and AX25 destinations, and is mainly used for compressed forwarding.
To use the telnet proxy server on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
TTYLINKPORT
TCP port for TTYLINK server (default=87).
The TTYLINK port was originally intended for direct one-to-one chat. However, since XRouter is most often used in unattended mode, TTYLINK connections are now treated exactly the same as TELNET ones. If anyone needs to chat to the sysop, they can either use the YELL command, leave a message in the PMS, or try channel 1234 (sysops channel) on the CHAT server.
To use TTYLINK on a TCP service number below 1024 on the Linux stack, XRPi must be run from an account with root privileges or the program must have the CAP_NET_BIND_SERVICE capability flag set.
See the TCP-PORTS page for details of how to configure this port.
UIFLOOD
Alias for APRS N-n digipeating (default=WIDE).
APRS UI frames digipeated on the UIFLOOD address have their SSIDs decremented, but the digi doesn't insert its own callsign into the path. The "H" ("Has been repeated") bit is not set unless the SSID decrements to zero. XRPi ignores frames that it has already digipeated in the previous 9 seconds.
The UIFLOOD digipeater is enabled on a PORT by port basis by setting bit 9 (decimal 512) in the port's DIGIFLAG.
Note that the APRS "New-N Paradigm" dictates that this address should be set to a "state code", e.g. "GBR" for the UK.
UITRACE
- Alias for APRS N-n digipeating (default=TRACE).
APRS UI frames digipeated on the UITRACE address have their SSIDs decremented, and the digi inserts its own callsign into the path with the "H" ("Has been repeated") bit set. XRPi ignores frames that it has already digipeated in the previous 9 seconds.
The UITRACE digipeater is enabled on a PORT by port basis by setting bit 8 (decimal 256) in the port's DIGIFLAG.
Note that the APRS "New-N Paradigm" dictates that this address should be set to "WIDE".