[[cli]]
== Interactive CLI (`osmo-s1gw-cli`)

Unlike the other Osmocom projects, OsmoS1GW does not have a traditional
telnet/VTY interface.  Instead, it comes with `osmo-s1gw-cli` — an
interactive command-line shell built on Python's
https://cmd2.readthedocs.io/[cmd2] library.  It communicates with
OsmoS1GW via the REST interface (see <<rest>>), and provides a
convenient alternative to issuing raw HTTP requests.

[[cli_installation]]
=== Installation

`osmo-s1gw-cli` is available as the `osmo-s1gw-cli` binary package from
the Osmocom package repository (see <<running_binary_packages>>).

When building from source, the following Python packages are required:

* https://pypi.org/project/cmd2/[cmd2]
* https://pypi.org/project/tabulate/[tabulate]

Install via pip:

----
pip install cmd2 tabulate
----

Or via the system package manager (Debian/Ubuntu):

----
sudo apt install python3-cmd2 python3-tabulate
----

After `make install` (see <<running_building_installation>>), the CLI is available
system-wide as `osmo-s1gw-cli`.

[[cli_usage]]
=== Usage

----
osmo-s1gw-cli [-h] [-v] [-p PORT] [HOST]

  HOST   OsmoS1GW REST host/address (default: localhost)
  -p     REST port (default: 8080)
  -v     Enable verbose/debug logging
----

Once inside the shell, available commands can be listed with `help -v`
and per-command help is accessible with `help <command>`.  In addition
to tab-completion, output can be filtered (`CMD | grep ...`) or
redirected to a file (`CMD > FILE`).

[[cli_commands]]
=== Commands

==== `config_show`

Display the effective runtime configuration (see <<rest_config>>).

Example:

----
OsmoS1GW# config_show

[gtpu_kpi]
| Parameter   | Value     |
|-------------|-----------|
| enable      | False     |
| interval    | 3000      |
| table_name  | osmo-s1gw |

[pfcp]
| Parameter   | Value      |
|-------------|------------|
| laddr       | 127.0.3.1  |
| raddr       | 127.0.3.10 |

[rest]
| Parameter   |   Value |
|-------------|---------|
| port        |    8080 |
| swagger_ui  |    True |

[sctp_client]
| Parameter   | Value                                                    |
|-------------|----------------------------------------------------------|
| laddr       | 127.0.2.1                                                |
| raddr       | 127.0.2.10                                               |
| rport       | 36412                                                    |
| sockopts    | {'recbuf': 65536, 'sctp_nodelay': True, 'sndbuf': 65536} |

[sctp_server]
| Parameter   | Value                                                    |
|-------------|----------------------------------------------------------|
| laddr       | 127.0.1.1                                                |
| lport       | 36412                                                    |
| sockopts    | {'recbuf': 65536, 'sctp_nodelay': True, 'sndbuf': 65536} |
----

==== `fetch_openapi_spec`

Fetch the OpenAPI specification (JSON) from the server and display it.

==== `metrics_list`

Get a list of metrics, optionally filtered by type and/or name path.

----
Usage: metrics_list [-h] [-t {all,counter,gauge}] [PATH]

positional arguments:
  PATH                  Metric path prefix (dot-separated)

optional arguments:
  -t, --type {all,counter,gauge}
                        Metric type (default: all)
----

Example: obtaining PFCP association metrics.

----
OsmoS1GW# metrics_list pfcp.assoc
| Name                          | Type    |   Value |
|-------------------------------|---------|---------|
| pfcp.assoc_setup_req.timeout  | counter |      21 |
| pfcp.assoc_setup_req.tx       | counter |      22 |
| pfcp.assoc_setup_resp.rx      | counter |       0 |
| pfcp.assoc_setup_resp.rx_ack  | counter |       0 |
| pfcp.assoc_setup_resp.rx_nack | counter |       0 |
| pfcp.associated               | gauge   |       0 |
----

Example: listing all gauge metrics.

----
OsmoS1GW# metrics_list --type gauge
| Name                          | Type   |   Value |
|-------------------------------|--------|---------|
| pfcp.associated               | gauge  |       0 |
| s1ap.enb.num_sctp_connections | gauge  |       0 |
----

==== `pfcp_assoc_state`

Display the current PFCP association state.

----
OsmoS1GW# pfcp_assoc_state
| Parameter                 | Value      |
|---------------------------|------------|
| State                     | connected  |
| Local address             | 127.0.3.1  |
| Remote address            | 127.0.3.10 |
| Local Recovery TimeStamp  | 3967211233 |
| Remote Recovery TimeStamp | 3965211123 |
----

==== `pfcp_assoc_setup`

Initiate the PFCP Association Setup procedure.

==== `pfcp_assoc_release`

Initiate the PFCP Association Release procedure.

==== `pfcp_heartbeat`

Send a PFCP Heartbeat Request to the UPF and display the result.

----
OsmoS1GW# pfcp_heartbeat
Heartbeat succeeded

OsmoS1GW# pfcp_heartbeat
Heartbeat failed: timeout
----

==== `mme_list`

List the MMEs currently registered in the pool.

----
Usage: mme_list [-h] [-S {none,name,laddr,raddr}] [--reverse]

optional arguments:
  -S, --sort-by {none,name,laddr,raddr}
                        Sort by (default: none)
  --reverse             Reverse sort order
----

Example:

----
OsmoS1GW# mme_list
| Name   | Local address   | Remote address/port   | Allowed TACs   |
|--------|-----------------|-----------------------|----------------|
| mme0   | 127.0.2.1       | 127.0.2.10:36412      | all            |
| mme1   | 127.0.2.1       | 127.0.2.11:36412      | all            |
| mme2   | 127.0.2.1       | 127.0.2.12:36412      | all            |
----

==== `mme_add`

Add an MME to the pool.

----
Usage: mme_add -N NAME -ra RADDR [-h] [-la LADDR] [-rp RPORT] [--tac TAC_LIST]

Add an MME to the pool

required arguments:
  -N, --name NAME     MME name (example: mme0)
  -ra, --raddr RADDR  Remote address (example: 192.168.1.101)

optional arguments:
  -la, --laddr LADDR  Local address (default: any)
  -rp, --rport RPORT  Remote port (default: 36412)
  --tac TAC_LIST      Allowed TAC (Tracking Area Code)
----

Example:

----
OsmoS1GW# mme_add --name mme42 --raddr 192.168.1.101
----

==== `mme_info`

Show configuration details for a specific MME.

----
Usage: mme_info [-h] (-N NAME | -a ADDR[:PORT])

MME ID:
  -N, --name NAME          MME name (example: mme0)
  -a, --addr ADDR[:PORT]   MME address with optional port (default: 36412),
                           e.g. 192.168.1.1 or 192.168.1.1:36412
----

Example:

----
OsmoS1GW# mme_info --name mme0
| Parameter           | Value            |
|---------------------|------------------|
| Name                | mme0             |
| Local address       | any              |
| Remote address/port | 127.0.2.10:36412 |
| Allowed TACs        | all              |
----

==== `mme_delete`

Remove an MME from the pool.

----
Usage: mme_delete [-h] (-N NAME | -a ADDR[:PORT])

MME ID:
  -N, --name NAME          MME name (example: mme0)
  -a, --addr ADDR[:PORT]   MME address with optional port (default: 36412),
                           e.g. 192.168.1.1 or 192.168.1.1:36412
----

Example:

----
OsmoS1GW# mme_delete --name mme0
----

==== `enb_list`

List all currently connected eNBs.

----
Usage: enb_list [-h] [-S {handle,pid,state,genb_id,uptime}] [--reverse]

optional arguments:
  -S, --sort-by {handle,pid,state,genb_id,uptime}
                        Sort by (default: handle)
  --reverse             Reverse sort order
----

Example (address columns omitted for readability):

----
OsmoS1GW# enb_list
|   handle | PID       | Global-eNB-ID | State     | ... | MME name |   Uptime |   E-RABs |
|----------|-----------|---------------|-----------|~~~~~|----------|----------|----------|
|        0 | <0.699.0> | 001-01-0      | connected | ... | mme0     |      418 |        0 |
|        1 | <0.701.0> | 001-01-1      | connected | ... | mme0     |       33 |        3 |
|        2 | <0.703.0> | 001-01-2      | connected | ... | mme0     |     3600 |       20 |
----

==== `enb_info`

Show details for a specific eNB.  The eNB can be identified by any of
the following selectors:

----
Usage: enb_info [-h] (-H HANDLE | -P PID | -G GENBID |
                      --enb-sctp-aid AID | --mme-sctp-aid AID |
                      --enb-conn ADDR:PORT)

eNB ID:
  -H, --handle HANDLE      eNB handle (example: 0)
  -P, --pid PID            eNB process ID (example: 0.33.1)
  -G, --genbid GENBID      Global-eNB-ID (example: 262-42-1337)
  --enb-sctp-aid AID       eNB SCTP association identifier
  --mme-sctp-aid AID       MME SCTP association identifier
  --enb-conn ADDR:PORT     eNB connection address/port (example: 192.168.1.1:34650)
----

Example: selecting by handle.

----
OsmoS1GW# enb_info -H 8
| Parameter             | Value                   |
|-----------------------|-------------------------|
| eNB handle            | 8                       |
| PID                   | <0.715.0>               |
| Global-eNB-ID         | 001-01-8                |
| State                 | connected               |
| eNB saddr:sport (aid) | 127.0.1.10:57362 (5734) |
| MME saddr:sport (aid) | 127.0.2.1:73421 (5745)  |
| MME daddr:dport (aid) | 127.0.2.10:36412 (5745) |
| MME name              | mme0                    |
| Uptime (s)            | 521                     |
| # E-RABs              | 99                      |
----

==== `enb_delete`

Force-disconnect an eNB, terminating its SCTP connection.  Accepts the
same selectors as `enb_info`.

==== `enb_erab_list`

List the E-RABs associated with a specific eNB.

----
Usage: enb_erab_list [-h] [-f] [-S {pid,state,mme_ue_id,erab_id}]
                     [--reverse]
                     (-H HANDLE | -P PID | -G GENBID |
                      --enb-sctp-aid AID | --mme-sctp-aid AID |
                      --enb-conn ADDR:PORT)

optional arguments:
  -f, --full   Print full table including PFCP and GTP-U F-TEID columns
  -S, --sort-by {pid,state,mme_ue_id,erab_id}
               Sort by (default: pid)
  --reverse    Reverse sort order
----

Example:

----
OsmoS1GW# enb_erab_list -G 001-01-0
| PID       |   MME-UE-S1AP-ID |   E-RAB-ID | State      |
|-----------|------------------|------------|------------|
| <0.707.0> |             4242 |          0 | erab_setup |
| <0.708.0> |             4242 |          1 | erab_setup |
| <0.709.0> |             4242 |          2 | erab_setup |
----

==== `erab_list`

List all E-RABs across all connected eNBs.  Accepts the same `-f`,
`--sort-by`, and `--reverse` options as `enb_erab_list`.

==== `erab_info`

Show details for a specific E-RAB, identified by its process ID.

----
Usage: erab_info -P PID

required arguments:
  -P, --pid PID  E-RAB process ID (example: 0.33.1)
----

Example:

----
OsmoS1GW# erab_info -P 0.714.0
| Parameter      | Value                |
|----------------|----------------------|
| PID            | <0.714.0>            |
| MME-UE-S1AP-ID | 4242                 |
| E-RAB-ID       | 1                    |
| State          | erab_setup           |
| SEID (local)   | 0x0000000000000002   |
| SEID (remote)  | 0x5454434e2d330001   |
| U2C F-TEID     | 0x00010001@127.0.0.1 |
| C2U F-TEID     | 0x01010001@127.0.1.1 |
| A2U F-TEID     | 0x02020001@127.0.2.2 |
| U2A F-TEID     | 0x00020001@127.0.0.2 |
----

==== `erab_delete`

Terminate an E-RAB FSM process, triggering PFCP Session Deletion.

----
Usage: erab_delete -P PID

required arguments:
  -P, --pid PID  E-RAB process ID (example: 0.33.1)
----

// vim:set ts=4 sw=4 et:
