<p>laforge <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-hlr/+/19052">View Change</a></p><div style="white-space:pre-wrap">Approvals:
  Jenkins Builder: Verified
  pespin: Looks good to me, but someone else must approve
  laforge: Looks good to me, approved

Objections:
  fixeria: I would prefer this is not merged as is

</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">manual: describe subscriber import by SQL<br><br>It seems a bad idea to cement the internal SQL structure in the user manual,<br>but since we currently lack a safe and portable import mechanism (like CSV<br>import in osmo-hlr-db-tool), this is currently valuable info to users.<br><br>Change-Id: I3246e6d5364215a71c33b5aca876deab7b6cfd70<br>---<br>M doc/manuals/chapters/running.adoc<br>M doc/manuals/chapters/subscribers.adoc<br>2 files changed, 81 insertions(+), 1 deletion(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc</span><br><span>index ff75c7f..1f1bcdc 100644</span><br><span>--- a/doc/manuals/chapters/running.adoc</span><br><span>+++ b/doc/manuals/chapters/running.adoc</span><br><span>@@ -54,7 +54,7 @@</span><br><span> </span><br><span> Alternatively, you may use the `osmo-hlr-db-tool`, which is installed along</span><br><span> with `osmo-hlr`, to bootstrap an empty database, or to migrate subscriber data</span><br><span style="color: hsl(0, 100%, 40%);">-from an old 'OsmoNITB' database. See `osmo-hlr-db-tool --help`.</span><br><span style="color: hsl(120, 100%, 40%);">+from an old 'OsmoNITB' database. See <<db_import_nitb>>.</span><br><span> </span><br><span> === Multiple instances</span><br><span> </span><br><span>diff --git a/doc/manuals/chapters/subscribers.adoc b/doc/manuals/chapters/subscribers.adoc</span><br><span>index ab41b0f..3bd5879 100644</span><br><span>--- a/doc/manuals/chapters/subscribers.adoc</span><br><span>+++ b/doc/manuals/chapters/subscribers.adoc</span><br><span>@@ -127,3 +127,83 @@</span><br><span> ----</span><br><span> <1> Randomly generated 5 digit MSISDN</span><br><span> <2> Disabled CS and PS NAM prevent the subscriber from accessing the network</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Import Subscriber Data</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Scripted Import</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+WARNING: It is not generally a good idea to depend on the HLR database's internal table structure, but in the lack of an</span><br><span style="color: hsl(120, 100%, 40%);">+automated import procedure, this example is provided as an ad-hoc method to aid automated subscriber import. This is not</span><br><span style="color: hsl(120, 100%, 40%);">+guaranteed to remain valid.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE: We may add CSV and other import methods to the `osmo-hlr-db-tool`, but so far that is not implemented. Contact the</span><br><span style="color: hsl(120, 100%, 40%);">+community if you are interested in such a feature being implemented.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE: `sqlite3` is available from your distribution packages or `sqlite.org`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Currently, probably the easiest way to automatically import subscribers to OsmoHLR is to write out a text file with SQL</span><br><span style="color: hsl(120, 100%, 40%);">+commands per subscriber, and feed that to `sqlite3`, as described below.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A difficulty is to always choose subscriber IDs that are not yet in use. For an initial import, the subscriber ID may be</span><br><span style="color: hsl(120, 100%, 40%);">+incremented per subscriber record. If adding more subscribers to an existing database, it is necessary to choose</span><br><span style="color: hsl(120, 100%, 40%);">+subscriber IDs that are not yet in use. Get the highest ID in use with:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sqlite3 hlr.db 'select max(id) from subscriber'</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A full SQL example of adding a single subscriber with id 23, IMSI 001010123456789, MSISDN 1234, Ki for COMP128v1, and K</span><br><span style="color: hsl(120, 100%, 40%);">+and OPC for Milenage:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+INSERT subscriber (id, imsi, msisdn) VALUES (23, '001010123456789', '1234');</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+INSERT INTO auc_2g (subscriber_id, algo_id_2g, ki)</span><br><span style="color: hsl(120, 100%, 40%);">+VALUES(23, 1, '0123456789abcdef0123456789abcdef');</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+INSERT INTO auc_3g (subscriber_id, algo_id_3g, k, op, opc)</span><br><span style="color: hsl(120, 100%, 40%);">+VALUES(23, 5, '0123456789abcdef0123456789abcdef',NULL,'0123456789abcdef0123456789abcdef');</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Table entries to `auc_2g` and/or `auc_3g` may be omitted if no such key material is required.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+UMTS Milenage auth (on both 2G and 3G RAN) is configured by the `auc_3g` table. `algo_id_3g` must currently always be 5</span><br><span style="color: hsl(120, 100%, 40%);">+(MILENAGE).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The algorithm IDs for `algo_id_2g` and `algo_id_3g` are:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Algorithm IDs in OsmoHLR's database</span><br><span style="color: hsl(120, 100%, 40%);">+[options="header",width="50%",cols="40%,60%"]</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+|`algo_id_2g` / `algo_id_3g` | Authentication Algorithm</span><br><span style="color: hsl(120, 100%, 40%);">+| 1 | COMP128v1</span><br><span style="color: hsl(120, 100%, 40%);">+| 2 | COMP128v2</span><br><span style="color: hsl(120, 100%, 40%);">+| 3 | COMP128v3</span><br><span style="color: hsl(120, 100%, 40%);">+| 4 | XOR</span><br><span style="color: hsl(120, 100%, 40%);">+| 5 | MILENAGE</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Create an empty HLR database with</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-hlr-db-tool -l hlr.db create</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Repeat above SQL commands per subscriber, incrementing the subscriber ID for each block, then feed the SQL commands for</span><br><span style="color: hsl(120, 100%, 40%);">+the subscribers to be imported to the `sqlite3` command line tool:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sqlite3 hlr.db < subscribers.sql</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[db_import_nitb]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Import OsmoNITB database</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To upgrade from old OsmoNITB to OsmoHLR, use `osmo-hlr-db-tool`:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-hlr-db-tool -l hlr.db import-nitb-db nitb.db</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Be aware that the import is lossy, only the IMSI, MSISDN, nam_cs/ps and 2G auth data are set.</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-hlr/+/19052">change 19052</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-hlr/+/19052"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-hlr </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I3246e6d5364215a71c33b5aca876deab7b6cfd70 </div>
<div style="display:none"> Gerrit-Change-Number: 19052 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: daniel <dwillmann@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: dexter <pmaier@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>