add OsmoHLR manual, OsmoHLR VTY reference

Change-Id: Ieb6a362a26a7e65199f68f5cd32d9b6b0e5d0fbf

1 files changed, 90 insertions, 0 deletions

diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..09388c0
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,90 @@
+== Running OsmoHLR
+
+The OsmoHLR executable (`osmo-hlr`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-hlr* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'DATABASE']
+
+=== OPTIONS
+
+*-h, --help*::
+	Print a short help message about the supported options
+*-V, --version*::
+	Print the compile-time version number of the OsmoBTS program
+*-d, --debug 'DBGMASK','DBGLEVELS'*::
+	Set the log subsystems and levels for logging to stderr. This
+	has mostly been superseded by VTY-based logging configuration,
+	see <<logging>> for further information.
+*-D, --daemonize*::
+	Fork the process as a daemon into background.
+*-c, --config-file 'CONFIGFILE'*::
+	Specify the file and path name of the configuration file to be
+	used. If none is specified, use `openbsc.cfg` in the current
+	working directory.
+*-s, --disable-color*::
+	Disable colors for logging to stderr. This has mostly been
+	deprecated by VTY based logging configuration, see <<logging>>
+	for more information.
+*-T, --timestamp*::
+	Enable time-stamping of log messages to stderr. This has mostly
+	been deprecated by VTY based logging configuration, see
+	<<logging>> for more information.
+*-e, --log-level 'LOGLEVEL'*::
+	Set the global log level for logging to stderr. This has mostly
+	been deprecated by VTY based logging configuration, see
+	<<logging>> for more information.
+*-l, --database 'DATABASE'*::
+	Specify the file name of the SQLite3 database to use as HLR/AUC
+	storage
+
+=== Bootstrap the Database
+
+Before first launching OsmoHLR, you need to create a database, which can be
+done with these commands:
+
+----
+mkdir -p /var/lib/osmocom
+sqlite3 /var/lib/osmocom/hlr.db < /usr/share/doc/osmo-hlr/hlr.sql
+----
+
+Depending on your installation choices, you will probably find `hlr.sql` in one
+of these locations:
+
+- `/usr/share/doc/osmo-hlr/hlr.sql`
+- `/usr/local/share/doc/osmo-hlr/hlr.sql`
+- in `osmo-hlr.git`'s source tree at `sql/hlr.sql`
+
+NOTE: At the time of writing, OsmoHLR does not create an initial empty database
+automatically, like OsmoNITB did. This behavior may be added in the future.
+
+=== Multiple instances
+
+Running multiple instances of `osmo-hlr` on the same computer is possible if
+all interfaces (VTY, CTRL) are separated using the appropriate configuration
+options. The IP based interfaces are binding to local host by default. In order
+to separate the processes, the user has to bind those services to specific but
+different IP addresses and/or ports.
+
+The VTY and the Control interface can be bound to IP addresses from the loopback
+address range, for example:
+
+----
+line vty
+ bind 127.0.0.2
+ctrl
+ bind 127.0.0.2
+----
+
+The GSUP interface can be bound to a specific IP address by the following
+configuration options:
+
+----
+hlr
+ gsup
+  bind ip 10.23.42.1
+----
+
+NOTE: At the time of writing, OsmoHLR lacks a config option to change the GSUP
+port, which is by default TCP port 4222.