From 2dc827c5bec61958da1db40e4fcafadabf8920a2 Mon Sep 17 00:00:00 2001 From: Heikki Hannikainen Date: Fri, 31 Aug 2012 10:05:45 +0000 Subject: [PATCH] Documentation additions git-svn-id: http://repo.ham.fi/svn/aprsc/trunk@775 3ce903b1-3385-4e86-93cd-f9a4a239f7ac --- doc/BUILDING.md | 42 ++++++++------ doc/CONFIGURATION.md | 134 ++++++++++++++++++++++++++++++++++++++++++- doc/INSTALLING.md | 4 +- doc/README.md | 14 ++--- src/Makefile.in | 2 +- src/aprsc.conf | 7 +-- 6 files changed, 168 insertions(+), 35 deletions(-) diff --git a/doc/BUILDING.md b/doc/BUILDING.md index 49e35f6..449aba2 100644 --- a/doc/BUILDING.md +++ b/doc/BUILDING.md @@ -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 diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md index 55cb41d..4728a7a 100644 --- a/doc/CONFIGURATION.md +++ b/doc/CONFIGURATION.md @@ -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 + + diff --git a/doc/INSTALLING.md b/doc/INSTALLING.md index 5300966..c3f99a0 100644 --- a/doc/INSTALLING.md +++ b/doc/INSTALLING.md @@ -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: diff --git a/doc/README.md b/doc/README.md index 9b863b6..6dace1a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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 -------------- diff --git a/src/Makefile.in b/src/Makefile.in index cee6ba3..9b5f2c1 100644 --- a/src/Makefile.in +++ b/src/Makefile.in @@ -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) diff --git a/src/aprsc.conf b/src/aprsc.conf index 2afc9f5..e2dc58e 100644 --- a/src/aprsc.conf +++ b/src/aprsc.conf @@ -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 # "LogRotate 10 5" keeps 5 old files of 10 megabytes each.