blob: 333f9b66fa485379a99a6d7e30160d59ac61fabd [file] [log] [blame]
Scott Bakere59540c2021-08-02 11:51:54 -07001..
2 SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org>
3 SPDX-License-Identifier: Apache-2.0
4
5Subscriber and Connectivity Management
6======================================
7
8Subscriber management includes workflows associated with provisioning new subscribers, removing
9existing subscribers, and associating subscribers with virtual connectivity services.
10
Sean Condonf918f642021-08-04 14:32:53 +010011.. note::
12 This section refers to a fully installed ROC GUI, properly secured and with Enterprises, Connectivity Services
13 and Sites already configured by a ROC Administrator. The examples shown below are taken from an example
14 configuration shipped with the ROC - the "MEGA Patch" (see :ref:`posting-the-mega-patch`)
15
Scott Bakere59540c2021-08-02 11:51:54 -070016Provisioning a new UE
17---------------------
18
19Before a UE can be granted connectivity service, it must first be provisioned. This step is normally
20performed by Aether Operations.
21
22Each UE is assigned a PLMN and a set of security keys. Depending on the deployment scenario, these
23keys might be shared by several UEs, or they might be unique to each UE. The allocation of PLMNs and
24keys is currently performed manually by the Aether Operations team. This subscriber-related
Zack Williams1ae109e2021-07-27 11:17:04 -070025detail is configured via the SIM Management application, ``Simapp``.
Scott Bakere59540c2021-08-02 11:51:54 -070026
Zack Williams1ae109e2021-07-27 11:17:04 -070027``simapp.yaml`` needs to be adjusted to include the new UE IMSIs to the subscriber list. For example::
Scott Bakere59540c2021-08-02 11:51:54 -070028
29 # simapp.yaml
30 # ...
31 simapp.yaml:
32 info:
33 version: 1.0.0
34 description: SIMAPP initial local configuration
35 logger:
36 # network function
37 APP:
38 debugLevel: info
39 ReportCaller: false
40 configuration:
41 provision-network-slice: false
42 subscribers:
43 - ueId-start: 123456789123458
44 ueId-end: 123456789123458
45 plmnId: 20893
46 opc: 8e27b6af0e692e750f32667a3b14605d
47 key: 8baf473f2f8fd09487cccbd7097c6862
48 sequenceNumber: 16f3b3f70fc2
49 - ueId-start: 123456789123460
50 ueId-end: 123456789123465
51 plmnId: 20893
52 opc: 8e27b6af0e692e750f32667a3b14605d
53 key: 8baf473f2f8fd09487cccbd7097c6862
54 sequenceNumber: 16f3b3f70fc2
55
Zack Williams1ae109e2021-07-27 11:17:04 -070056TODO: This file will probably be placed under GitOps control once the 5G ROC is deployed. Document
Scott Bakere59540c2021-08-02 11:51:54 -070057the new location of the file.
58
Sean Condon435be9a2021-08-06 14:28:37 +010059.. _configure_device_group:
60
Scott Bakere59540c2021-08-02 11:51:54 -070061Configure Connectivity Service for a new UE
62-------------------------------------------
63
Sean Condonf918f642021-08-04 14:32:53 +010064To receive connectivity service, a UE must be added to a DeviceGroup. An Enterprise is typically
65organized into one or more Sites, each Site which may contain one or more DeviceGroups. Navigate
66to the appropriate DeviceGroup which is associated with the Site you wish to deploy on, and add
Scott Bakere59540c2021-08-02 11:51:54 -070067the UE's IMSI to the DeviceGroup.
68
Sean Condonf918f642021-08-04 14:32:53 +010069The Site details can be seen by navigating to the Site list view.
Scott Bakere59540c2021-08-02 11:51:54 -070070
Sean Condonf918f642021-08-04 14:32:53 +010071.. image:: images/aether-roc-gui-sites-list.png
72 :width: 755
73 :alt: Sites List View in Aether ROC GUI showing site details
74
75In the ROC GUI, navigate to the Device Groups list view, to see the list of
76Device Groups and their association to Sites.
77
78 |DEVICEGROUP-LIST|
79
Zack Williams1ae109e2021-07-27 11:17:04 -070080In the DeviceGroup *New York POS* example above an IMSI Range **store** of
81**70-73** will mean the set of IMSI IDs (when the *format* specifier of the
82*starbucks-newyork* Site are applied to its *MCC*, *MNC* and *Enterprise*) of
Sean Condonf918f642021-08-04 14:32:53 +010083
84* 021032002000070 (021-032-002-000070)
85* 021032002000071
86* 021032002000072
87* 021032002000073
88
89.. note::
90 For 4G service, a UE may participate in at most one DeviceGroup, and that DeviceGroup may
91 participate in at most one VCS. For 5G service, a UE can participate in many DeviceGroups, and each
92 DeviceGroup may participate in many VCSes.
93
94Editing
95*******
96Edit the DeviceGroup by clicking on the Edit icon, and in the Edit page,
97adjust an existing range or create a new range (by clicking on the `+` icon).
98
99 |DEVICEGROUP-EDIT|
100
101The following restrictions apply
102
Zack Williams1ae109e2021-07-27 11:17:04 -0700103#. The IMSI ID specified in "from" or "to" is relative to *MCC*, *MNC* and *Enterprise* of the Site.
104#. The maximum value of an IMSI ID is defined by the number of **S** characters in the `format` specifier of the Site.
105#. IMSI Ranges are contiguous ranges of IMSI IDs. To accommodate non contiguous IMSI IDs, add extra Ranges.
106#. IMSI Ranges can have a maximum span of 100 between "from" and "to" IMSI IDs. Break bigger spans in to many ranges.
107#. IMSI ranges within a DeviceGroup cannot not overlap.
Sean Condonf918f642021-08-04 14:32:53 +0100108
109When the entries on the DeviceGroup edit page are valid the **Update** will become available
110
111* Click this to add the changes to the **Basket** of configuration changes
112* Observe that the **Basket** icon (2nd icon from top right) displays the number of changes
113
114.. note::
115 The changes are not committed to **aether-config** until the **Basket** is committed.
116 This allows several changes to be gathered together in one transaction and checked before committing.
117
Sean Condon435be9a2021-08-06 14:28:37 +0100118.. _committing:
119
Sean Condonf918f642021-08-04 14:32:53 +0100120Committing
121**********
122To commit the changes
123
124#. click on the **Basket** icon (2nd icon from top right) to see the Basket view
125#. inspect the changes to be committed (optional)
126#. click **commit** to perform the commit
127#. observe the response that's temporarily displayed that shows the success or failure of the commit
128
129.. image:: images/aether-roc-gui-basket-view-new-range.png
130 :width: 635
131 :alt: Basket View with some changes ready to be committed
Scott Bakere59540c2021-08-02 11:51:54 -0700132
133Remove Connectivity Service from an existing UE
134-----------------------------------------------
135
Sean Condonf918f642021-08-04 14:32:53 +0100136Using the ROC GUI, navigate to the DeviceGroup that contains the UE,
Scott Bakere59540c2021-08-02 11:51:54 -0700137then remove that UE's IMSI from the list. If you are removing a single UE, and the
138DeviceGroup is configured with a range specifier that includes several IMSIs,
139then it might be necessary to split that range into multiple ranges.
140
Zack Williams1ae109e2021-07-27 11:17:04 -0700141* If the UE to be removed has an IMSI ID in the middle of an existing IMSI Range:
142 click the *trash can* icon next to that *IMSI Range* and
143 use the *+* icon to add new Ranges for the remaining IMSI IDs.
144* Alternatively if the UE to be removed has an IMSI ID at the start or end of an existing IMSI Range:
Sean Condonf918f642021-08-04 14:32:53 +0100145 then adjust the *from* or *to* value accordingly.
Scott Bakere59540c2021-08-02 11:51:54 -0700146
Sean Condonf918f642021-08-04 14:32:53 +0100147 |DEVICEGROUP-EDIT|
148
149.. note::
150 The UE may continue to have connectivity until its next detach/attach cycle.
Scott Bakere59540c2021-08-02 11:51:54 -0700151
152Create a new DeviceGroup
153------------------------
154
155DeviceGroups allow UEs to be grouped and configured together. Each site comes preconfigured with
156a default DeviceGroup, but additional DeviceGroups may be created. For example, placing all IP
157Cameras in an my-site-ip-cameras DeviceGroup would allow you to group IP Cameras together.
158
Sean Condonf918f642021-08-04 14:32:53 +0100159To add a DeviceGroup, navigate to the list of DeviceGroups and click `Add` in the upper right.
Zack Williams1ae109e2021-07-27 11:17:04 -0700160(This may be grayed out if you do not have appropriate permissions).
Sean Condonf918f642021-08-04 14:32:53 +0100161
162* Specify a unique **id** for the DeviceGroup
163 40 characters max and only alphanumeric and `-`, `_` and `.` allowed
164* Choose a *Site* from the list of preconfigured list
Zack Williams1ae109e2021-07-27 11:17:04 -0700165 It will not be possible to add IMSI Ranges until the Site is chosen
166* IMSI Ranges can be added at this stage or later
Sean Condonf918f642021-08-04 14:32:53 +0100167
168.. image:: images/aether-roc-gui-devicegroup-add.png
169 :width: 490
170 :alt: Adding a new Device Group requires an *id* and choosing a Site
Scott Bakere59540c2021-08-02 11:51:54 -0700171
172Delete a DeviceGroup
173--------------------
174
Sean Condonf918f642021-08-04 14:32:53 +0100175If a DeviceGroup is no longer needed, it can be deleted. Deleting a DeviceGroup will not cause
Scott Bakere59540c2021-08-02 11:51:54 -0700176the UEs participating in the group to automatically be moved elsewhere.
177
Sean Condonf918f642021-08-04 14:32:53 +0100178.. note::
179 If a Device Group is being used by an existing VCS, then it cannot be removed.
180 Delete the VCS first, and then the DeviceGroup.
181
182A DeviceGroup can be deleted from the DeviceGroup list view, by clicking the *trash can* icon
183next to it. The deletion is added to the **Basket** directly. Navigate to the *Basket View*
184to commit the change.
185
186 |DEVICEGROUP-LIST|
187
Scott Bakere59540c2021-08-02 11:51:54 -0700188
189Add a DeviceGroup to a Virtual Connectivity Service (VCS)
190---------------------------------------------------------
191
192In order to participate in the connectivity service, a DeviceGroup must be associated with
193a Virtual Connectivity Service (VCS).
194
Sean Condonf918f642021-08-04 14:32:53 +0100195Navigate to the *VCS* list view to see the list of VCS's and their associations to DeviceGroups.
196
Sean Condon435be9a2021-08-06 14:28:37 +0100197 |VCS-LIST|
Sean Condonf918f642021-08-04 14:32:53 +0100198
199To edit a *VCS* click on the *edit* button next to it in this list.
200
201This brings up the VCS edit page where (among many other things) zero, one or many
202DeviceGroups can be associated with it.
203
204* Click the *trash can* symbol to remove a DeviceGroup from the VCS
205* Click the *+* icon to add a DeviceGroup
206* Click the *Allow* slider to Allow or Disallow the DeviceGroup
207 This is a way of disabling or reenabling the DeviceGroup within a VCS without having to remove it
208
209.. image:: images/aether-roc-gui-vcs-edit.png
210 :width: 562
211 :alt: VCS Edit View in Aether ROC GUI showing DeviceGroup association editing
Scott Bakere59540c2021-08-02 11:51:54 -0700212
213Remove a DeviceGroup from a Virtual Connectivity Service (VCS)
214--------------------------------------------------------------
215
Sean Condonf918f642021-08-04 14:32:53 +0100216The procedure is covered in the above section.
Scott Bakere59540c2021-08-02 11:51:54 -0700217
Sean Condon435be9a2021-08-06 14:28:37 +0100218.. _monitor_device_group:
219
220Monitoring a DeviceGroup
221------------------------
222
223The performance of a Device Group can be monitored in many ways, by clicking its |monitor| (**monitor**) icon:
224
225* From the *VCS Monitor* page, which shows all DeviceGroup's belonging to an VCS.
226* From the DeviceGroup List Page - click the |monitor| icon for the DeviceGroup.
227* When editing an existing DeviceGroup - in the Edit page, the |monitor| is next to the *id*
228
229The *monitor* page itself shows:
230
231* An information Panel for each *IMSI Range* in the *DeviceGroup*
232
233 * Each UE has a |monitor| button that allows further drill down
Zack Williams1ae109e2021-07-27 11:17:04 -0700234 * Each UE is shown with its fully expanded IMSI number (a combination of *IMSI ID* and *Site* parameters)
Sean Condon435be9a2021-08-06 14:28:37 +0100235* An information panel for the *Site* and *IP Domain* of the *DeviceGroup*
236
237 * Clicking on the down arrow expands each panel
238
239.. image:: images/aether-roc-gui-devicegroup-monitor.png
240 :width: 600
241 :alt: DeviceGroup Monitor View with UE links and information panels
242
243The per UE Monitor panel contains:
244
245* a graph of the UE's Throughput and Latency over the last 15 minutes
246* a graph of the UE's connectivity over the last 15 minutes
247
248.. image:: images/aether-roc-gui-ue-monitor.png
249 :width: 600
250 :alt: DeviceGroup Monitor View with UE links and information panels
251
252
253.. |monitor| image:: images/monitor-icon.png
254 :width: 28
255 :alt: Monitor icon
256
Sean Condonf918f642021-08-04 14:32:53 +0100257.. |DEVICEGROUP-LIST| image:: images/aether-roc-gui-devicegroups-list.png
258 :width: 755
Zack Williams1ae109e2021-07-27 11:17:04 -0700259 :alt: Device Groups List View in Aether ROC GUI showing Site association and IMSI Range of all DeviceGroups
Sean Condonf918f642021-08-04 14:32:53 +0100260
261.. |DEVICEGROUP-EDIT| image:: images/aether-roc-gui-devicegroup-edit.png
262 :width: 755
Zack Williams1ae109e2021-07-27 11:17:04 -0700263 :alt: Device Groups Edit View in Aether ROC GUI showing IMSI Range
Sean Condon435be9a2021-08-06 14:28:37 +0100264
265.. |VCS-LIST| image:: images/aether-roc-gui-vcs-list.png
266 :width: 920
267 :alt: VCS List View in Aether ROC GUI showing DeviceGroup association