Documentation additions
git-svn-id: http://repo.ham.fi/svn/aprsc/trunk@775 3ce903b1-3385-4e86-93cd-f9a4a239f7ac
This commit is contained in:
Heikki Hannikainen
parent
509a7bd7f6
commit
2dc827c5be
|
|
@ -8,8 +8,8 @@ EITHER.
|
|||
|
||||
If you're familiar with compiling software from the source code, and
|
||||
pre-built binary packages are not available for your platform, this is where
|
||||
you need to start. Binary packages will be provided shortly for Debian and
|
||||
Ubuntu systems.
|
||||
you need to start. Binary packages are provided for Debian and Ubuntu
|
||||
systems.
|
||||
|
||||
aprsc has been built and tested on:
|
||||
|
||||
|
|
@ -29,8 +29,8 @@ mostly on your own.
|
|||
Prerequirements and dependencies
|
||||
-----------------------------------
|
||||
|
||||
aprsc requires a recent gcc version (4.1) to compile due to the need for
|
||||
built-in functions for atomic memory access.
|
||||
aprsc requires a recent gcc version (4.1 or later) to compile due to the
|
||||
need for built-in functions for atomic memory access.
|
||||
|
||||
aprsc also requires libevent2 (libevent version 2.0), since libevent's HTTP
|
||||
server is used to implement the status page and HTTP position upload
|
||||
|
|
@ -46,24 +46,27 @@ libevent2 is also available in MacPorts for OS X and FreeBSD ports.
|
|||
Downloading aprsc
|
||||
--------------------
|
||||
|
||||
Head to http://he.fi/aprsc/down/
|
||||
|
||||
Head to http://he.fi/aprsc/ !
|
||||
|
||||
|
||||
Compiling aprsc
|
||||
------------------
|
||||
|
||||
Delete old version if necessary:
|
||||
Delete old version if necessary:
|
||||
|
||||
$ rm aprsc-latest.tar.gz
|
||||
|
||||
Download the latest source tree:
|
||||
Download the latest source tree:
|
||||
|
||||
$ wget http://he.fi/aprsc/down/aprsc-latest.tar.gz
|
||||
|
||||
Extract it:
|
||||
$ tar xvfz aprsc-latest.tar.gz
|
||||
Extract it:
|
||||
|
||||
Go to the newly-created directory and configure the build:
|
||||
$ cd aprsc-1.0.0
|
||||
$ tar xvfz aprsc-latest.tar.gz
|
||||
|
||||
Go to the newly-created directory and configure the build:
|
||||
|
||||
$ cd aprsc-1.0.0 (or whatever)
|
||||
$ ./configure
|
||||
|
||||
At this point the configuration either succeeds or fails. If it fails, it is
|
||||
|
|
@ -85,12 +88,15 @@ should probably work.
|
|||
|
||||
With build configuration done:
|
||||
|
||||
Compile it:
|
||||
Compile it:
|
||||
|
||||
$ make
|
||||
|
||||
Install it:
|
||||
$ make install
|
||||
|
||||
Install example configuration:
|
||||
$ make installconf
|
||||
Install it:
|
||||
|
||||
$ sudo make install
|
||||
|
||||
Install example configuration:
|
||||
|
||||
$ sudo make installconf
|
||||
|
||||
|
|
|
|||
|
|
@ -2,5 +2,137 @@
|
|||
Configuring aprsc
|
||||
=================
|
||||
|
||||
TODO: write it.
|
||||
Command line parameters and startup
|
||||
--------------------------------------
|
||||
|
||||
aprsc understands a few command line parameters. On Ubuntu/Debian derived
|
||||
systems these go to /etc/default/aprsc, on other systems they go in the init
|
||||
script starting up the software.
|
||||
|
||||
* -u aprsc: switch to user 'aprsc' as soon as possible
|
||||
* -t /opt/aprsc: chroot to the given directory after starting
|
||||
* -f: fork to a daemon
|
||||
* -e info: log at level info (can be changed to "debug" for more verbose
|
||||
logging)
|
||||
* -o file: log to file (can be changed to "stderr" for supervisord and debugging, or "syslog"
|
||||
for syslogd)
|
||||
* -r logs: log file directory, log files are placed in /opt/aprsc/logs
|
||||
* -c etc/aprsc.onf: configuration file location
|
||||
|
||||
Since the daemon chroots to /opt/aprsc, all paths are relative to
|
||||
that directory and the daemon cannot access any files outside
|
||||
the chroot.
|
||||
|
||||
aprsc can log to syslog too, but that'd require bringing the
|
||||
syslog socket within the chroot.
|
||||
|
||||
|
||||
Configuration file options in aprsc.conf
|
||||
-------------------------------------------
|
||||
|
||||
### Basic server options ###
|
||||
|
||||
* ServerId NOCALL
|
||||
|
||||
This is your unique server ID. Typically contains either a callsign and
|
||||
an SSID.
|
||||
|
||||
* PassCode 0
|
||||
|
||||
This is the passcode for your server ID.
|
||||
|
||||
* MyAdmin "My Name, MYCALL"
|
||||
|
||||
Your name and callsign.
|
||||
|
||||
* MyEmail email@example.com
|
||||
|
||||
This is an email address where you, the server operator, can be
|
||||
contacted. It is not displayed on the status web page, but it goes to
|
||||
the machine-readable status.json file, so persons skilled in the art
|
||||
can find a way to contact you.
|
||||
|
||||
* LogRotate megabytes filecount
|
||||
|
||||
If logging to a file (-o file), this option enables built-in log rotation.
|
||||
"LogRotate 10 5" keeps 5 old files of 10 megabytes each.
|
||||
|
||||
|
||||
### Timers and timeouts ###
|
||||
|
||||
Timer settings assume the time is specified in seconds, but allow appending
|
||||
one of s, m, h, d to multiply the given value by the number of seconds in a
|
||||
second, month, hour and day respectively. Examples:
|
||||
|
||||
* 600 - 600 seconds
|
||||
* 600s - 600 seconds
|
||||
* 5m - 5 minutes
|
||||
* 2h - 2 hours
|
||||
* 1h30m - 1 hours 30 minutes
|
||||
* 1d3h15m24s - you get it?
|
||||
|
||||
And here are the contestants:
|
||||
|
||||
* UpstreamTimeout 15s
|
||||
|
||||
When no data is received from an upstream server in N seconds,
|
||||
disconnect and switch to another server.
|
||||
|
||||
* ClientTimeout 48h
|
||||
|
||||
When no data is received from a downstream client in N seconds,
|
||||
disconnect.
|
||||
|
||||
### Port listeners ###
|
||||
|
||||
The *Listen* directive tells aprsc to listen for connections from the network.
|
||||
The basic syntax is:
|
||||
|
||||
Listen socketname porttype tcp address to bind port options...
|
||||
|
||||
|
||||
* socketname: any name you wish to show up in logs and statistics
|
||||
|
||||
* porttype: one of:
|
||||
|
||||
- fullfeed - everything, after dupe filtering
|
||||
- igate - igate / client port with user-specified filters
|
||||
- udpsubmit - UDP packet submission port (8080)
|
||||
- dupefeed - duplicate packets dropped by the server
|
||||
|
||||
* options: one more of:
|
||||
|
||||
- filter "m/500 t/m" - force a filter for users connected here.
|
||||
If you wish to specify multiple filters, put them in the same "string",
|
||||
separated by spaces.
|
||||
- maxclients 100 - limit clients connected on this port (defaults to 200)
|
||||
- acl etc/client.acl - match client addresses against ACL
|
||||
- hidden - don't show the port in the status page
|
||||
|
||||
#
|
||||
# If you wish to provide UDP service for clients, set up a
|
||||
# second listener on the same address, port and protocol.
|
||||
#
|
||||
# The "::" is IPv6 "IN6ADDR_ANY", whereas "0.0.0.0" is same
|
||||
# with IPv4.
|
||||
#
|
||||
# On FreeBSD you need to have separate listeners for IPv4 and
|
||||
# IPv6. On Linux, just use :: alone - the IPv6 listener will
|
||||
# catch the IPv4 connections just as well.
|
||||
#
|
||||
# Example of normal server ports for Linux, supporting both TCP and UDP,
|
||||
# IPv4 and IPv6:
|
||||
#
|
||||
Listen "Full feed" fullfeed tcp :: 10152 hidden
|
||||
Listen "" fullfeed udp :: 10152 hidden
|
||||
|
||||
Listen "Client-Defined Filters" igate tcp :: 14580
|
||||
Listen "" igate udp :: 14580
|
||||
|
||||
#Listen "350 km from my position" fullfeed tcp :: 20350 filter "m/350"
|
||||
#Listen "" fullfeed udp :: 20350 filter "m/350"
|
||||
|
||||
Listen "UDP submit" udpsubmit udp :: 8080
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -70,11 +70,11 @@ upgrade when upgrades are available.
|
|||
sudo apt-get upgrade
|
||||
|
||||
Before starting aprsc edit the configuration file, which can be found in
|
||||
/opt/aprsc/etc/aprsc.conf. Please see the CONFIGURING file for
|
||||
/opt/aprsc/etc/aprsc.conf. Please see the CONFIGURATION file for
|
||||
instructions.
|
||||
|
||||
To enable startup, edit /etc/default/aprsc and change STARTAPRSC="no" to
|
||||
"yes".
|
||||
"yes". There should not be any need to touch the other options at this time.
|
||||
|
||||
Start it up:
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ cycles are currently very quick - be ready to upgrade on a short notice when
|
|||
new versions are announced. Like any new software, aprsc is likely to
|
||||
contain new bugs, and some upgrades might have a high priority.
|
||||
|
||||
If you're not prepared to upgrade often, please wait for a few months – it
|
||||
If you're not prepared to upgrade often, please wait for a few months, it
|
||||
should be more peaceful then. Documentation is not there yet, either, but
|
||||
if you're an experienced APRS-IS server operator, there should be no big
|
||||
surprises around.
|
||||
|
|
@ -59,7 +59,7 @@ If you need a nice, compact igate software for Linux, please take a look at
|
|||
either aprsg, aprx, or aprs4r. If you need to run an APRS-IS server on
|
||||
Windows or some other platform not supported by aprsc, or if you need the
|
||||
features existing in javAPRSSrvr which are missing from aprsc, javAPRSSrvr
|
||||
is the right choice for you – it's got a lot of good features that many of
|
||||
is the right choice for you - it's got a lot of good features that many of
|
||||
you need, and it works on virtually all operating systems. If you need an
|
||||
igate for Windows, APRSIS32 should be good.
|
||||
|
||||
|
|
@ -74,8 +74,8 @@ libevent2 library, no other extra libraries are needed.
|
|||
|
||||
Linux and OS X are the main development environments and will receive
|
||||
premium support, but FreeBSD and Solaris 11 are known to work too. Packaged
|
||||
binaries for Debian and Ubuntu will be available shortly for super-easy
|
||||
installations and automatic upgrades.
|
||||
binaries for Debian and Ubuntu are available for super-easy installations
|
||||
and automatic upgrades using APT.
|
||||
|
||||
|
||||
Design
|
||||
|
|
@ -143,7 +143,7 @@ An HTTP thread runs an event-driven HTTP server (libevent2 based) to support
|
|||
the status page and HTTP position uploads. Since implementing nice web user
|
||||
interfaces in plain C is not very convenient or effective, the status page
|
||||
is produced using modern Web 2.0 methods. The HTTP server can only generate
|
||||
a dynamic JSON-encoded status file and spit out static files. An empty
|
||||
a dynamic JSON-encoded status file and serve static files. An empty
|
||||
index.html file loads a static JavaScript file, which then periodically
|
||||
loads the JSON status data and formats the contents of the status page
|
||||
within the client's browser. This approach allowed clean separation of
|
||||
|
|
@ -153,10 +153,6 @@ Both developers are experienced professional Unix C programmers, so the
|
|||
programming language was easy to select. We also had plenty of existing
|
||||
code that could be re-used in this project.
|
||||
|
||||
In hindsight, aprsc is slightly over-engineered and over-optimized for the
|
||||
current real-word requirements. Performance, however, appears to match
|
||||
the initial goals.
|
||||
|
||||
|
||||
Performance
|
||||
--------------
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ make-rpm: # actually just a reminder of how to do it..
|
|||
MARKDOWN=perl ../tools/Markdown.pl
|
||||
WEBDOCS=/data/www/hes/html/aprsc
|
||||
DOCS=README.md INSTALLING.md BUILDING.md CONFIGURATION.md
|
||||
DESTDOCS=$(addprefix $(WEBDOCS)/,$(basename $(DOCS)))
|
||||
DESTDOCS=$(addprefix $(WEBDOCS)/,$(addsuffix .html,$(basename $(DOCS))))
|
||||
SRCDOCS=$(addprefix ../doc/,$(DOCS))
|
||||
install-webdoc: $(DESTDOCS)
|
||||
$(DESTDOCS): $(SRCDOCS)
|
||||
|
|
|
|||
|
|
@ -5,16 +5,15 @@
|
|||
ServerId NOCALL
|
||||
# Passcode for the server ID
|
||||
PassCode 0
|
||||
MyEmail email@example.com
|
||||
# Who is running this server?
|
||||
MyAdmin "My Name, MYCALL"
|
||||
# The email address where the admin can be reached
|
||||
MyEmail email@example.com
|
||||
|
||||
### Directories #########
|
||||
# Data directory (for persistent state files - currently none)
|
||||
RunDir data
|
||||
|
||||
# Log directory
|
||||
LogDir logs
|
||||
|
||||
# If logging to a file (-o file), enable built-in log rotation.
|
||||
# LogRotate <megabytes> <filecount>
|
||||
# "LogRotate 10 5" keeps 5 old files of 10 megabytes each.
|
||||
|
|
|
|||
Loading…
Reference in New Issue