BKG Professional NtripCaster Version 2.0.x
Operations Manual

1. Versions

The BKG Professional NtripCaster is meant for service providers handling several hundred incoming streams in support of thousand or more simultaneously listening clients. The BKG Professional NtripCaster software follows NTRIP Version 2. The main advantages over NTRIP Version 1.0 include:

2. Installation instructions

Here is what you need to do to get the software up and running:

  1. Copy it somewhere into an empty directory, run bunzip2 ntripcaster-version.tar.bz2 and tar xfv ntripcaster-version.tar for un-compression.
  2. Run ./configure (if you do not want the server to be installed in /usr/local/ntripcaster, specify the desired path with ./configure --prefix=<path>)
  3. Run make
  4. Run make install
  5. After that, the server files will be installed. Binaries will be in /usr/sbin and /usr/bin, configuration files in /etc/ntripcaster, logs in /var/log/ntripcaster and html templates in /usr/local/ntripcaster/templates.
  6. Go to the configuration directory and copy clientmounts.aut.dist, sourcemounts.aut.dist, users.aut.dist, groups.aut.dist, sourcetable.dat.dist and ntripcaster.conf.dist to clientmounts.aut, users.aut, groups.aut, sourcetable.dat and ntripcaster.conf. Change the contents of these files according to your needs.

If you need detailed information about the program's setup and operation, have a look into files README and INSTALL as well.
For any other technical questions please contact igs-ip@bkg.bund.de.

3. Start and stop of NtripCaster

The recommended home directory for NtripCaster installation is /usr/local/ntripcaster. Below this home directory the sub-directories bin, conf, log, templates and var can be found.

Sub-directory bin contains the:

You can start the NtripCaster using the command ./ntripcaster start.
You can restart the NtripCaster using the command ./ntripcaster restart.
You can stop the NtripCaster using the command ./ntripcaster stop.

Note that casterwatch should never crash. In case ntripdaemon crashes or is shut down for re-configuration reasons, casterwatch shall restart it within a few seconds.

4. The NtripCaster Web Interface

The NtripCaster’s home page is http://NtripCasterIP:Port/home.

The NtripCaster’s Administrator’s Web Interface is located at http://NtripCasterIP:Port/admin. Note that access to the Admin Web Interface is password protected. If port 80 is used, make sure that no other web servers are running on port 80 on the same machine.

Sub-directory templates contain templates for the Admin Web Interface http://NtripCasterIP:Port/admin as well as the NtripCaster’s home page http://NtripCasterIP:Port/home.

5. Main NtripCaster configuration file

The essential parameters for running the NtripCaster are defined in ntripcaster.conf under sub-directory conf. Most of the parameters are self-explanatory. Note that neither ntripcaster.conf nor any other configuration file of the NtripCaster should be edited on a MS Windows system because this adds an extra ‘carriage return’ at the end of each record that may cause a problem.

6. Client authentication/authorization

The NtripClient authorization is configured through the files users.aut, groups.aut and clientmounts.aut under sub-directory conf.

Example:

A taxi company in Sydney wants to enable each of its 100 drivers to receive a specific DGPS corrections stream through individual accounts. Since no more than 30 drivers are ever on duty at the same time, the company applied (and most likely paid) for access rights for a maximum of 30 concurrent clients only.

  1. In users.aut we need to configure 100 user accounts: 
    taxi1:password1
    taxi2:password2
    taxi3:password3
    …
    taxi100:password100
  2. In groups.aut we then create a group company, listing all the 100 users but putting a limit of 30 concurrent users 
    company:taxi1,taxi2,taxi3,…,taxi100:30
  3. In clientmounts.aut we then allow the group company to access the DGPS corrections stream from mountpoint SYDNEY 
    /SYDNEY:company

7. Server authentication/authorization

An NtripServer intending to occupy an existing mountpoint using the new NTRIP Version 2.0 protocol must have an account in users.aut defined as a member of a group of accounts in groups.aut which is authorized to use that mountpoint through a valid entry in sourcemounts.aut.

An NtripServer intending to occupy an existing mountpoint via NTRIP Version 1.0 must use either the generic encoder_password as defined in ntripcaster.conf or the password of a user who is a member of a group authorized by a valid entry in sourcemounts.aut. For security reasons, we recommend to enter an encoder_password in ntripcaster.conf that is difficult to decrypt and that you do not pass it on. Instead, we recommend that NTRIP Version 1.0 uploads should also be defined via explicitly entered user accounts, similar to NTRIP Version 2.0.

Please note: If no encoder_password is entered in ntripcaster.conf, the default password letmein , which is defined in the source code in the ntripcaster.h file, takes effect.

Example:

In users.aut we may have registered "provider1" (user ID) with password "password1" through:

provider1:password1

In groups.aut we may then configure provider1 as a member of group gupload through:

gupload:provider1,provider2,provider3,…

In sourcemounts.aut we may then allow the members of group gupload to upload a stream to mountpoint SYDNEY through:

/SYDNEY:gupload
In order to prevent an unauthorized upload to a not defined mountpoint, the keyword default may be used. 
default:group1
In this example, group1 is allowed to upload data streams to any undefined mountpoints.
Vice versa, no other group will be allowed to do that.
Please note, that unlike all other mountpoint entries in sourcemounts.aut, this option start without a slash "\". We recommend to always set the default-parameter for security reasons.

8. Administration through Web Interface

The NtripCaster knows administrator and operator groups whose members perform administrative and operational duties and responsibilities through the Admin Web Interface http://NtripCasterIP:Port/admin. These groups are defined in groups.aut and receive their specific responsibility through the "admin" and "oper" admin-mountpoints in clientmounts.aut. The groups may be named FirstAdmin, SecondAdmin, and NTRIPAdmin.

Some basic monitoring and administration tasks can be accomplished through the various menus of the web interface:

9. Administration through Telnet

The NtripCaster can also be administrated/operated via telnet. However, we always recommend an administration via the Web Interface for security reason. If you still want to start a telnet session to the NtripCaster, use a command window and enter the following two commands: 
telnet NtripCasterIP 2101
ADMIN [admin_password]
where 2101 stands for the NtripCaster’s listening port and admin_password is taken from ntripcaster.conf. Then press Enter twice.

Starting from NtripCaster 2.0.36, only about 4 seconds remain for entering the admin password before the software closes the connection.

You may now use any of the administration/operation commands described in Commands used with telnet:
help, admins, alias, allow, auth, deny, kick, list, listeners, oper, quit, rehash, relay, set, sources, stats, tail, tell, uptime

The execution of some of these commands requires operator rights. To become an operator, use the "oper" command: oper oper_password. Note that neither the admin_password nor the oper_password has anything to do with the passwords listed in users.aut. These two passwords are defined in ntripcaster.conf.

Note further that none of the configuration changes made through the Telnet admin commands are permanent! As soon as the NtripCaster is restarted, the contents of the basic configuration files becomes active again.

10. The Sourcetable

The NtripCaster’s sourcetable is defined in the file sourcetable.dat under sub-directory conf. Note that the NtripCaster delivers a so-called dynamic Sourcetable to NtripClients on their request. This dynamic Sourcetable is generated from sourcetable.dat but comprises only those streams/mountpoints that are available for the NtripCaster at the time when the request is received. Streams that have an outage will not show up.

11. Changes in NtripCaster configuration

Permanent configuration changes must be made in the configuration files ntripcaster.conf, users.aut, groups.aut, clientmounts.aut, sourcemounts.aut, and sourcetable.dat. They become active through Admin Web Interface commands.

12. Log files

Daily log files are saved under sub-directory logs. The NtripCaster maintains three types of log files:
access-yymmdd.log, ntripcaster-yymmdd.log and usage-yymmdd.log.

Note that files of type access-yymmdd.log follow the CSV format. You may like to upload these files to an external archive and by that rename its suffix to *.csv for read compatibility with the MS Excel program. The contents of these files may become the base for an accounting system.

Date,Time,User,IP,Station,Client,Seconds,Bytes
10/Aug/2007,20:42:31,hr,141.74.33.2,BURG0,NTRIP BNC 1.4,86,15166
10/Aug/2007,20:42:32,hr,141.74.33.2,MOBS1,NTRIP BNC 1.4,87,10873
...

The NtripCaster does not delete these daily log files. Check the disk space from time to time and delete them manually when necessary. Note that the size of the log files may become very large depending on parameter logfiledebuglevel defined in ntripcaster.conf.

13. Security aspects

The recommended home directory for NtripCaster installation is /usr/local/ntripcaster. This implicitly requires running the NtripCaster software as root. However for security reasons it could be of interest to run the NtripCaster software as a normal user. If you want to do so, you have to take into account that a user application cannot open ports <=1024. In order to allow the caster software to use port 80 although running it as a normal user, the following steps may have to be executed by your system administrator: After that, in the NtripCaster configuration file ntripcaster.conf the port entry has to be changed from port 80 to xxxx (with xxxx being 1080 in this example). The NtripCaster software can now be started using a normal user account. After all, the NtripCaster would still be available through port 80.

14. Communication via SSL/TLS

The NtripCaster has no built-in support for TLS encryption but there exist several tools to add this functionality in form of a proxy server. One of them is stunnel.

The Apache HTTP Server offers this functionality as well but comes with a more complicated installation and configuration. This section has kindly been provided by Wim Aerts, Royal Observatory of Belgium. It guides you through setting up an Apache 2 HTTP Server instance to add SSL/TLS to your NtripCaster. It only deals with getting things to work, not with securing issues. For that the reader is referred to https://www.ssllabs.com/ssltest/index.html and relevant documents on that website.

Take the following steps:
  1. Find out on what port your NtripCaster is listening, e.g. at port 2101.
  2. Select a port that you would like to use to offer a secure SSL access to your NtripCaster, e.g. port 443.
  3. Configure Apache 2 HTTP Server to also listen on the port you selected in step 2. This is done by adding a statement 'Listen 443' to your global Apache 2 HTTP Server configuration file. On Ubuntu systems this should be added to file /etc/apache2/ports.conf.
  4. Set up a new virtual host that will take care of the SSL and proxy to the NtripCaster. This is done by adding the following code. Please specify the correct file location for your certificate and key file. 
        <IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ProxyPreserveHost On
        ProxyRequests Off
        ProxyPass / http://localhost:2101/
        ProxyPassReverse / http://localhost:2101/
        SSLEngine On
        SSLProtocol -all +SSLv3 +TLSv1
        SSLCipherSuite TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:
        SSLOptions +StrictRequire
        SSLCertificateFile    /etc/ssl/certs/...
        SSLCertificateKeyFile /etc/ssl/private/...
        <Directory />
            SSLRequireSSL
            Allow from all
        </Directory>
    </VirtualHost>
    </IfModule>

    This should go somewhere in the Apache 2 HTTP Server configuration file(s). On Ubuntu it is placed in a separate file, e.g.: /etc/apache2/sites-available/mysite. Command a2ensite mysite will then 'enable' this 'available' site.

  5. Make sure that the Apache 2 HTTP Server is configured to load all the modules needed to do what you desire. You need at least modues mod_mime, mod_proxy, mod_proxy_http and mod_ssl.
  6. Start or restart the Apache 2 HTTP Server deamon. On Ubuntu this can be done through /etc/init.d/apache2 restart. Check the error log files.
  7. Put on the URL bar https://ip_of_your_NtripCaster:443 in your browser to check the connection. You should see the sourcetable now.
  8. If the test at step 7 fails, check firewalls.
Note that SSL support makes only sense for NTRIP Version 2. Stream transport through SSL and NTRIP Version 1 would have a problem because it is not fully HTTP compatible.
Also note that username and password are base64 encoded if Ntrip Version 2 is used!

15. LDAP

LDAP (Lightweight Directory Access Protocol) is a communication protocol for data exchange within a computer network that allows the request and modification of information provided by a directory service. Because LDAP is based on the client server principle it describes the communication between LDAP client and directory server. From such a directory that is realized as hierarchical database object-related data can be selected.

For data privacy reasons LDAP functionality is implemented for user authentication. Currently only simple LDAP access is supported. In case of LDAP usage usernames need to be added in normal configuration as well instead (e.g. simply add * as password in users.aut file), but for password checks LDAP is used: The NTRIP Caster, acting as LDAP client, formulates a request containing user name and password mentioned within the NTRIP client/server request and gets the answer “success” in case of congruence or “failure” otherwise from the LDAP server. LDAP authentication is normally disabled. It gets enabled when an LDAP server is specified in ntripcaster.conf: 

ldap_server 127.0.0.1
Furthermore, the settings ldap_uid and ldap_people_context in ntripcaster.conf are required for the LDAP request formulation: 
ldap_uid_prefix uid
ldap_people_context ou=people
The bind call is done with '{prefix}={user},{context}'.

Appendix

Commands used with telnet

alias

The alias command is used for two things: It can be used to add an alias for a local mountpoint so that a stream can be accessed from two mountpoints. Or it can be used to add an alias for a remote NtripCaster stream.
Syntax: 
            alias add <mountpoint> <newmountpoint>
            alias del <mountpoint>
            alias list

allow and deny

This adds a hostmask to an internal access lists (acl). It specifies that this hostmask should allow or deny access. A type for this acl can be specified, which can be either all, client, source or admin. It only has affect on the specified connection type.
Syntax: 
            allow|deny <client|source|admin|all> add <hostmask>
            allow|deny <client|source|admin|all> del <hostmask>
            allow|deny <client|source|admin|all> list
Examples: 
            allow client add *.se
            allow all del *.netcom.com
            deny admin add *.se
            deny admin del ap.*.com
            allow admin list

admins

The admins command is used to list the admins connected to the server. It will display one admin connection per line, like: 
            Admin 341 <d66.ryd.student.liu.se> connected for 1 hours, 8 minutes and 14 seconds. 0 commands issued
A host-mask as an argument can be supplied, and only the admins who match the mask, will be shown.
Syntax: 
            admins <hostmask>
Example: 
            admins *.ifag.de

help

Without arguments, the command help prints a list of all commands and what they are used for. With a command as an argument, a slightly longer description of what the command does, is printed.
Syntax: 
            help [command]
Examples: 
            help kick
            help

kick

This command can be used to get rid of some listeners, admins, or sources. A single connection may be kicked out as well as all connections of a certain type matching a hostmask.
Syntax: 
            kick <id>
            kick <-acs> <hostmask>
            kick <hostmask>
Examples: 
            kick 314
            kick -a *.com
            kick *.badsource.com

listeners

This command displays a list of all connected listeners. The output can be restricted to those listeners matching a specific hostmask.
Syntax: 
            listeners [hostmask]
Example: 
            listeners *.ifag.de

oper

Most commands on the admin console are restricted to NtripCaster operators. To obtain operator privileges, the oper command with the NtripCaster operator password as argument can be used.
Syntax: 
            oper <operator password>

quit

The quit command is used to leave the NtripCaster admin console. This can only be used, when the console is accessed through the remote interface (e.g. using telnet). An optional argument will be used as a signoff message, e.g. displayed to other connected admins.
Syntax: 
            quit [message]

rehash

This command can be used after changing parameters in the NtripCaster configuration file (ntripcast.conf or sourcetable.dat). When used with an argument, it will understand this argument as a filename and parse this as a configuration file.
Syntax: 
            rehash [filename]
Example: 
            rehash /tmp/newrtcmast.conf

sources

sources is used just like listeners to view all the connected sources. It can be used with an optional argument to limit the list to only the sources matching the specified hostmask. It also accepts a large number of options. By default the output is defined by the variable default_sourceopts.
Syntax: 
            sources [hostmask] [-options]
The options are as follows: 
    i - Connection id
    s - Socket descriptor
    t - Time of connect
    p - Connection ip
    h - Hostname
    c - Connection state
    y - Source type
    c - Number of clients
    d - Dumpfile
    r - Mountpoint priority
    M - Source mountpoint
    R - Bytes read
    W - Show bytes written
    C - Total client connects
    T - Time connected
Example: 
            sources *.apan.com –aCW

set

This command is used without arguments. set will display a list of all NtripCaster variables and their current values. It can be used also to change any of those variables if the name is specified and the new value is entered as arguments. Typing „help settings“ will give a short description of all the settings, and a longer description for the settings is available here.
Syntax: 
            set
            set <variable name>
            set <variable name> <new value>
Examples: 
            set client_timeout
            set max_clients 580

stats

The stats command will print some information about the current number of connections, averages on client connections, bytes read and written, etc. It looks a lot like the output available from the statistics file. As an argument, „hourly“ or „daily“ can be put. Then the averages and totals for the last hour or day will be printed.
Syntax: 
            stats [hourly|daily]

tail

The tail command can be issued by an administrator to display messages written to the log file. It's similar to the unix tail command.

tell

An admin can send a message to all other connected admins using the tell command. Any argument will be send to all admins.
Syntax: 
            tell <message>

uptime

The uptime command is similar to the Unix uptime command. It prints the number of days, hours, minutes and seconds the NtripCaster is up and running.

list

This command is used to list all connections, sources, admins, or clients.
Syntax: 
            list [hostmask]
Example: 
            list *.toomanyarguments.com

relay

To pull a stream from a remote server, the relay command should be used.
Syntax: 
            relay pull [-s] [-2] [-i <userID:pass>] [-m <localmount>] <caster-URL>
Example: 
            relay pull -2 -i user1:password1 -m WTZR0 igs-ip.net:2101/WTZR00DEU0

auth

This command is used to display authorization users, mounts and groups.
Syntax: 
            auth <groups|users|mounts>
Example: 
            auth groups
            auth users

TLS - Hints and Tips

OpenSSL

Please make sure that you have installed the OpenSSL development package.

Certificates

The certificates are expected to be in directory /etc/ssl/certs. You can also put them in another directory. In this case, when compiling the software, the directory for your certs must be specified explicitly.
Syntax: 
configure --with-tls-certs-dir=</mycerts>
Certificates must be in individual files in .pem format. Each .pem file starts with a line -----BEGIN CERTIFICATE----- and ends with line -----END CERTIFICATE-----.
Certs from the certificate authorities (CA) should already be installed on your system. Nevertheless, it might be necessary to split them in individual files, as mentioned above.

OpenSSL expects the certificates with hashed file names. These hashed file names consist of a hash obtained from OpenSSL, with a numerical extension starting at 0.
Syntax: 

openssl x509 -hash -noout -in <mycert.pem>
A more convenient Example, generating hashed links for all .pem files in your directory: 
for file in *.pem;do ln -s "$file" "$(openssl x509 -hash -noout -in "$file")".0; done

You may also install certificates for specific servers. Please note, that such certs must be renewed after some time.
Here's a convenient way to get such a cert. Do not forget to split the resulting file with an editor in individual .pem files: 
echo QUIT|openssl s_client -showcerts -connect igs-ip.net:443|awk '/-----BEGIN CERTIFICATE-----/ {p=1}; p; /-----END CERTIFICATE-----/ {p=0}' > <myfile.pem>