Administrator’s Guide

billing system
v. 5.3-005
 

Contents
1 License agreement
.................................................................8
2 Introduction
Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Notation conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
List of terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 System description
How to Connect the System to the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Structure of the UTM Billing System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
UTM Remote Function Access (URFA). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
User’s rights. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Version policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
External charges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Basic system objects
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
System users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
System groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Prepaid cards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Traffic classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Accounting periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Tariff plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Tariff plans compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Charge policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Periodic cost component recalculating rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Recalculation on block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Repay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
System block settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Time ranges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Coefficient scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
IP addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25


2
 

5 Installation and Initial Setup

Getting License Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Installing Basic Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Updating to version 5.3-004. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6 Administrator’s interface
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Common features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Tariffication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Reference book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Additional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Stray pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Tray icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7 Usage examples
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Installation and startup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating accounting periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating time ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Creating traffic classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Creating services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Creating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Removing a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Creating account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Removing an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Creating a charge policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Creating service links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Creating a tariff plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Creating tariff links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Linking a user to a house. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Linking a user to a bank. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Making payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Creating dealers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Setting dealer’s permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Linking users to dealers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Creating firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110


3
 

Creating firewall rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

8 System core
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Main Components of the Core. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Core settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9 UTM5 RADIUS
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
RADIUS protocol description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Workflow description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Session control mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
utm5_radius daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Core settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Dynamic IP address allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10 Text files import
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Workflow description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Utilities usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
11 UTM5 RFW
UTM5 RFW workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Firewall rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
utm5_rfw settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
12 UTM5 Dynashape
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Workflow description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
RADIUS parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
13 UTM5 Urfaclient
Warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
URFA scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Data files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
utm5_urfaclient utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Usage example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
14 Structured data import
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
XML file scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158


4
 

Example XML file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

15 Dealer module
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Creating dealers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Dealer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
16 Cashier module
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Creating cashiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Cashier interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
17 utm5_tray utility
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Installation and startup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Interface pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Tray icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
18 Web interface
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Entrance page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Interface pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Config files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
19 Hotspot module
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
20 DHCP
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Entities, used by UTM5 DHCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Processing a DHCP request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
21 IPTV integration module
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Common features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Creating and attaching IPTV service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
22 IP telephony module
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
List of terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Workflow description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Network organization schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193


5
 

23 UTM5 Traffic collector

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
24 Automatic registration of users
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Guest access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Access with automatic registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
25 E-mail notifications
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
26 System maintenance
Database backup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Database integrity verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Archiving of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
27 Auxiliary utilities
NetFlow statistics generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
RADIUS statistics generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
get_nf_direct utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
utm5_payment_tool utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
db_archiver utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
28 Appendix
Approaches to traffic shaping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Template variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209


6
 


7
 

License agreement 3
This License agreement (hereinafter "the Agreement") is a legal agreement made between you (natural or legal person,
hereinafter "the user") and NetUP company (hereinafter "NetUP") concerning the above software NetUP product, and
including the software, print materials, and any inline or electronic documentation (hereinafter "the product").
1. License scope.
1.1. One product set may be installed on only one computer.
1.2. The product is considered used if it is loaded in the RAM memory, or stored on hard disk, CD or other storing
device of a certain computer.
1.3. The user has a right to create an archive copy intended exclusively for individual use for the product recovery
or storing it on hard disk on condition that the original copy is stored as backup or archive copy.
2. The user rights and warranty services are rendered only to the registered users.
3. This license also refers to the original product updates and add-ons provided by NetUP, if not specified otherwise in
the accompanying documents.
4. The user may install a copy of the product on a second workstation for testing purposes. The user may NOT sell,
lease, rent or share his license with a third party.
5. Sharing or distributing the product or any part of it or the license key files is prohibited.
6. It is not allowed to disclose the technology or decompile the product, except in cases when despite this restriction
in the license agreement it is explicitly allowed by the active legislation, and to the degree that is clearly defined
therein.
7. NetUP has a right to terminate this agreement when its provisions and terms are violated by the user. In this case,
the user is obliged to destroy all available product copies and its components. Copyright infringement can lead to
substantial penalties according to Russian and international legal policies.
8. The user agrees that NetUP has a right to collect and use at its own discretion the technical data supplied by the
user to the support department of NetUP.
9. To the maximum degree allowed by the active legislation and under no circumstances, NetUP and its vendors are
liable for any special, occasional, direct or indirect damage, or loss (including without limitations the following: loss
of profit; loss of confidential or other information; loss caused by breakages in commercial or production
operations; damage to health; violation of privacy; non-fulfillment of any obligation including obligation to act
conscientiously and with reasonable precautions; loss caused by negligence; and any other property or other kind
loss) in result of use or impossibility to use the product, rendering or non-rendering maintenance services, or in
other cases envisaged or related to provisions of this license agreement, including violation of obligation, civil
offence (including negligence), impersonal (independent of guilt) liability for some damage, violation by NetUP or
its vendor of any contract or warranty liabilities, even if NetUP or its vendors have been notified in advance of this
possible damage. NetUP and its vendors are not liable and bear no obligations in case of this product unauthorized
use, which is not envisaged by this agreement.
10.This agreement becomes valid on the moment of installing the product.
11.All property rights, author's rightsfor this product and in relation to it belong to NetUP or its vendors. This product is
provided for use ("licensed"), not for sale.
12.Installation and maintenance of the product is provided by NetUP under a separate agreement.
13.License validity period is equal to the useful lifetime of the product according to technical conditions and is 9 years
since generation of the license key.


8
Intended audience 

Introduction 4
Intended audience
The present manual is intended for the providers of Internet and telephony services using the UTM5 billing system. The
document covers basic functionality of UTM5 v. 5.3-004, as well as the typical necessary actions during its startup,
deployment, and operation.

Notation conventions
The following elements are emphasized in the text:
Terms (on first occurrence)
Interface strings
Hyperlinks
Inline code pieces and commands

Code blocks

Notes

Warnings related to incomplete compatibility with older versions of UTM5

Generic warnings

List of terms

Networking
– DNS – (Domain Name Service) is a distributed system that translates human-readable domain names to numerical
IP addresses.
– TCP/IP – (Transmission Control Protocol / Internet Protocol) is a stack of protocols used in computer networks.
– HTTP – (Hypertext Transport Protocol) is an application layer network protocol.
– HTTPS – (HTTP Secure) is extension of HTTP enabling encrypted communication.
– UDP – (User Datagram Protocol) is a transport level network protocol used to transfer data without guaranteed
reliability.
– TCP – (Transmission Control Protocol) is a transport level network protocol used for reliable and ordered transfer
of data.
– MAC – (Media Access Control) is a level of communications system that provides addressing and channel access
control mechanisms.
– MAC address – is a unique identifier assigned to network interfaces for communications on the physical network
segment.
– SSL – (Secure Socket Layer) is a cryptographic network protocol.
– Switch – is a networking device that connects network segments.


9
List of terms 

Other terms
– XML – (eXtensible Markup Language) is a language for representing structured data.
– Database – is a system that organizes and stores large amounts of data.
– Cluster – is a group of connected computers used as a single computing facility.
– Billing system – is a system that automatically accounts for the use of services and sends bills to the customers.
– ISO – is the International Organization for Standardization.
– ANSI – is the American National Standards Institute.


10
How to Connect the System to the Network 

System description 5
How to Connect the System to the Network
A versatile nature of the billing system allows integrating it into existing or intended network infrastructure in various
ways. UTM5 can work with various hardware- and software-based routers and it doesn't limit the number of
communication paths (accounted for simultaneously) and types of devices arranging these paths. Hereinafter the main
commonly used variants are examined.
– Local network is connected to the Internet via a hardware-based router supporting statistics collection
Cisco, MikroTik, NSG, Revolution and other routers typically support export of the traffic statistics. In that case the
server with the billing system may be installed either inside or outside the local network (e.g. in the head office available
via Internet). Statistics is collected and routers are monitored remotely.

– Local network is connected to the Internet via switch or hardware-based router not supporting statistics collection.
This type of connection allows installing the billing system on a router or on a remote server. Statistics is read from a
router interface and processed by a local machine (in the former case), or it is transmitted via the network and
processed by another server (in the latter case).
Alongside with the above mentioned ways of local networks’ traffic counting, there are many other ways, e.g. counting
of uplinks, or any combination of the presented ways.
– Client connects to the Internet via dial-up
In this case the access server may be either Cisco or a PC-router with connected modems. Authorization of a user is
performed via RADIUS protocol. Tariffication is based either on connection time or on traffic.


11
Structure of the UTM Billing System 

– Client connects to the Internet using Wi-Fi

The system supports accounting for services of wireless access using the Wi-Fi technology also known as Hotspot.
This way of connection is often used in public places like hotels, cafeteria, or airports.

Structure of the UTM Billing System

The UTM billing system is a bunch of applications which mainly consists of three groups: the core of the system, the
administrator interface and the user interface.
The core of the system is launched on the server and is responsible for functioning of the billing system as a whole. It
is described in more details in System core on page 112. Besides the core, one might use auxiliary utilities responsible
for maintaining RADIUS protocol involving operations (see UTM5 RADIUS on page 119), log files import (see Text files
import on page 132), low level URFA operations (see UTM5 Urfaclient on page 150), payment systems interaction
and user web interface operation maintenance.
The administrator interface (see Administrator’s interface on page 31) is a Java application installed on the
administrator’s workstation and allowing to fine-tune and control the system. This application is platform independent
and can be run on any operating system, including Windows, Linux or FreeBSD.
The user interface is a set of programs working along with the web server and constituting the user's virtual office.
Along with the described interfaces, the core may interact with different routers and traffic information providers. It may
also interact with external applications using the NXT protocol.
Router

Traffic info provider Statistics

converter
Firewall rfw

Administrator’s
Cisco router interface
NetFlow NetFlow v5 or v9 Dealer’s
provider interface
rsh Cashier’s
Firewall
interface
VPN
NAS utm5_tray

Billing servers rfw utm5_urfaclient

HTTPS

RADIUS RADIUS auth.

HTTP

RADIUS acct. utm5_payment_tool

server
URFA

Core
Stream utm5_send_traffic
DHCP Stream server
server
NetFlow buffer utm5_send_cdr

DMS NXT v.1

URFA server clients
utm5_flowgen
NXT v.1 и NXT v.2 NXT v.1
Web Web URFA NXT v.2
servers NXT v.2
server interface clients

Рис. 1. UTM5 schematics

NXT (NetUP XML Transaction) – an application level protocol, using TCP as a transport protocol and SSL for data
encryption and sender authentication. A transaction is the basic data exchange unit. Each transaction may be
addressed to one or more system components and includes a set of events intended for processing by the receiving
component.
Stream - is a binary application level protocol, using TCP as the transport level protocol and meant for synchronous
communication.


12
UTM Remote Function Access (URFA) 

UTM Remote Function Access (URFA)

URFA is a module for access to the core of the system from external applications. It authorizes users according to
CHAP scheme and provides the work of a remote user. The protocol supports data transmission and function calls.
URFA checks up whether a certain user has access to the function called, and on positive check allows the user to start
the data exchange. Otherwise the access is rejected.
Each session is given a 128-bit replication-free system ID number (SID). SID can be used repeatedly to gain access
to the system. In case of transient error (when a session is being restored) SID is removed, and the user is prompted
to enter login and password once more. SID is related to the user’s IP address, and is removed automatically after some
downtime (see the web_session_timeout variable). An option of session restore is available, which requires the system
user’s rights.
After the session has been started, the table of permitted calls is created including a list of access rights and symbols
generated by the system. If, after the session has been started up, an additional module is loaded, the corresponding
calls will be listed as forbidden. In that case the user must log in once more.

User’s rights
Users of the system are split into two types: ordinal users (clients, subscribers) and administrators (system users).
Depending on the type, a user has some list of permitted operations. The clients are permitted to execute operations
with the identifier more than 0x80000000; other operations are accessed by administrators only. Only system users
are allowed to communicate over Stream, NXTv1 and NXTv2 protocols.

Version policy
Every new major release of UTM5 is preceded by the release candidate version(s), which are suitable for early feature
testing but not recommended to use in production. These are followed by the release version. If any critical problems
are discovered later, one or more update versions may be issued; these contain no new functionality as compared to
the release version, only the bug fixes.
It is recommended to install the latest update, or just the latest release if there are no updates to it.

Logging
If some system component needs to leave a log message, it passes the event level and message text to the logging
module.
Following event levels exist:

Level Name Description

0 EMERG Fatal error, system halted
1 ALERT Critical error, requires immediate action
2 CRIT Critical error
3 ERROR Non-critical error
4 Warn Warning
5 Notice Information that may worth noticing
6 Info General information
7 Debug Debugging information
8 Trace Additional debugging information
9 Stats Statistics

The logging module puts the text to the appropriate log stream, depending on the module settings and the event level.
The stream is associated with certain file also specified in the module settings. By default all streams are associated
with the standard error stream.


13
External charges 

There are following log streams:

Stream name Levels included

Critical From 0 to 2
Main From 0 to 3 + log_level
Debugging All

Some components may activate the built-in mechanism of log file rotation. At that, after logging an event the module
checks file size against some specified threshold. If the file size exceeds the threshold, the file is closed and renamed
to include a certain suffix. If the number of files is limited, the suffix is “ .0 " If the number of files is unlimited. the suffix
is " .<timestamp> ", where .<timestamp> is the Unix Time Stamp of file closing time. If a file with such suffix already
exists, the suffix is incremented. After that the number of files is also checked and older files are removed if the number
exceeds the limit.
Logging settings for each particular module are described in more detail later on.

External charges
UTM5 contains an integration module intended to work with Rentsoft system, which is a distributor of software and
digital content. The charges for the subscription are made along with the charges for the Internet services. Services
provided by Rentsoft are not included in the list of UTM5 services. The corresponding charges, however, are registered
and gathered in a special report, see Administrator’s interface: Custom charges report on page 66. The invoices
for these charges are issued immediately upon the charge-off.
For more details on the possible settings and parameters of the integration module, see:
rentsoft.ru/provider/new/netup_netup300/


14
Introduction 

Basic system objects 6

Introduction
This chapter lists the basic system objects and their relations. Relations of the basic system objects.

Рис. 2. Basic system objects may be split in two groups.

First group is composed of the objects having immediate effect on the system’s functioning, and includes:
– Traffic classes (page 17);
– Telephone zones;
– Telephone directions;
– Time ranges (page 23).
Second group contains the objects which affect the system indirectly, including:
– Tariff plans (page 18);
– Accounting periods (page 18);
– Services (page 18);
– Currencies (page 24).
To clarify the distinction further: a traffic class has immediate effect on the system, since it is used non-stop in the
classification of traffic data, as long as the system receives those data. On the other hand, currency has no direct
involvement in the everyday routine activities and is used only to prepare invoices or accept payments, thus being an
object of indirect effect.

Users
Users are the customers of services (IP traffic, telephony, etc.) controlled by the UTM5 billing system. A lot of operations
may be done with the users, including: assignment of services of different types, billing, making payments, viewing
statistics, etc.


15
Accounts 

Users may be combined in groups. Each user has one or more accounts, to which the services of various types may
be attached, either separately or in bundles as a part of a tariff plan.
There is a special variety of users called card users. Those are created via the activation of prepaid cards (see Prepaid
cards on page 17).
Interface for handling users is described in Administrator’s interface: Users on page 33. Group operations interface
is described in Administrator’s interface: Groups on page 38. Outlines of creation of users and other operations with
them are given in Creating users on page 102and the subsequent examples.

Accounts
User account is an object containing the financial information. Account may be linked to services in a form of service
links or tariff links.

Blockings
Account may get blocked, which suspends all services attached to it. UTM5 provides three block types:
1. System is a blocking type that is automatically triggered by the system in case the sum of the accounts balance and
credit becomes negative, or (in certain conditions) when the personal account's balance is not enough to charge for
the periodic component of the services cost, or when a traffic quota is exceeded.
2. Administrative is a blocking type that is manually triggered by an administrator.
3. User is manually triggered by the user via User interface e.g. in case the user goes on vacation and doesn't plan to
user the internet for a certain amount of time.
For each block type one can set additional parameters, such as periodic fee or prepaid traffic recalculation. These and
several more parameters can be managed via Charge policy settings (see Recalculation on block on page 22and
Creating a charge policy on page 47).

Keep in mind that when a user account is blocked, the Internet parameter in the personal account properties
is always switched Off, but is not always switched On when the blocking ends. If the Auto enable inet option
for the Internet parameter in the user account settings is not checked, and the account was unblocked manually,
one also has to manually change the internet status for this user.

Interface for handling accounts is located on the user properties page (see page 35). Creation of accounts and other
operations with them are described in page 103and subsequent examples.

System users
System users a special class of users having the rights to administrate the system using the UTM control center.
System users have negative user ID. An ordinary user can not be an administrator at the same time, and vice versa.
By default, the following system users exist in the system:
– init – is the top-level administrator;
– web – is the system account for the web interface;
– radius – is the system account for the RADIUS server.
– rfw – is the system account for the RFW daemon.
– dhcp – Is the system account for the DHCP server.
– collector – Is the system account for the Traffic collector daemon.
A system user has the following properties: login, password, subnet the user is allowed to login from, and list of system
groups to which the user belongs.
Interface for handling system users is described in Administrator’s interface: System users on page 37.


16
System groups 

System groups
The access rights of a system user are determined by the system group where the user belongs. For simultaneous
members of multiple groups, the privileges are summarized among all groups. All calls for forbidden operations are
registered in the system core journal. Initially the following system groups exist in the system:
– Wheel – is the group of administrators (all functions permitted).
– Dealers – may create users, assign services and make payments.
Interface for handling system groups is described in Administrator’s interface: System groups on page 38.

Prepaid cards
may work with prepaid cards intended for activation via web interface (see Web interface on page 177) or via the
utm5_tray application (see utm5_tray utility on page 173). A card may have either limited term of use, or an
expiration date.
If the card is activated on the entrance page, a card user is generated by the system. User’s login is set to card_NUM,
where card_ is the value of system parameter card_user_prefix (see System core: Settings available in the
administrator’s interface on page 117) and NUM is the card number. User’s balance is set to the card balance value.
If the card has a tariff plan attached to it, the services from the plan will be attached to the user’s personal account. If
the card has limited term of use, its balance goes to the user’s account in a form of expiring payment (see Payments
on page 24) with this term of expiration.
Otherwise, i.e. if the card is activated by an already existing user, the card’s balance is added to the user’s account,
and the tariff plan associated with the card (if any) is ignored.
Interface for handling users is described in Administrator’s interface: Card users on page 37. Creation of prepaid
cards is described in Administrator’s interface: Card pools on page 39.

Traffic classes
Traffic running towards a user and back is divided to several classes. Certain rules specify a set of attributes combining
traffic records into classes. Traffic classes may be defined using any NetFlow v5 attributes. They are: affiliation of
source or recipient's IP address with any subnet, port of source or recipient, autonomous system of source or recipient,
network protocol, next router (hop), TOS, TCP flags, router interface via which a packet goes. Additionally, a traffic
record may be related to a certain class depending on time and date.
Traffic belongs to a class if:
– it belongs to one of its subclasses;
– it does not belong to any its subclass with Skip option set;
– it came during the accounting period set for this class.
Traffic is checked against all classes in the decreasing order by ID until first match. If no match has been found, the
traffic is attributed to the class with ID=0 (unclassified).
Traffic subclass is a set of features (may include the data from NetFlow records and the IP address of the NetFlow
provider) that determine the attribution of the traffic to the particular class, or negation thereof.
Traffic subclass is a set of features (may include the data from NetFlow records and the IP address of the NetFlow
provider) that determine the attribution of the traffic to the particular class, or negation thereof.
Traffic belongs to a subclass if:
– sender and destination addresses belong to the corresponding networks set in the subclass parameters;
– the rest of NetFlow record parameters is compatible with those stated in the subclass properties;
– IP address of the NetFlow provider coincides with that set in the subclass properties, or none are set.
Interface for handling traffic classes and subclasses is described in Administrator’s interface: Traffic classes on
page 43.


17
Accounting periods 

Accounting periods
An accounting period is a period of time to which various periodic activities are related (such as charge-off for periodic
services). Standard accounting periods are: daily, weekly, monthly, quarterly, annual, and period of fixed amount of
days.
Keeping general directory of accounting periods allows settling invoices with all users or with groups of users at the
same time, e.g., from the first day of a month till the first day of the next month.
When an accounting period is closed, the following operations are performed:
– recalculation of subscription fee and prepaid traffic (considering blockings);
– transfer of the prepaid traffic left (if any) to the next accounting period;
– charge-offs;
– automatic change of tariff plan, if requested;
– resetting balance to zero for those user accounts that have this option checked;
– if Dynashape module is present (see UTM5 Dynashape on page 148): issue of Delete bandwidth limit events for
the IP addresses of service links subject to shaping, and execution of the corresponding firewall rules
– automatic creation of a new accounting period. The new period starts exactly at the end of the one being closed, and
effectively stands in its place for all purposes, i.e. has the same type, duration, number of charges, and is connected
to the same service and/or tariff link(s).
Interface for handling accounting periods is described in Administrator’s interface: Accounting periods on page 46.

Tariff plans
A tariff plan is a bundle of services provided as a package. The system allows creating those packages, and then to
assign the whole package to users at once. On attaching a tariff plan to a user it is necessary to select an accounting
period and define settings for the services. A tariff plan may be set up to prolong automatically onto the next accounting
period, or to switch to another compatible plan at the end of period.
Interface for working with tariff plans is described in Administrator’s interface: Tariff plans on page 42. User
accounts are linked to tariff plans via tariff links (see Creating tariff links on page 107).

Tariff plans compatibility

In order to switch the tariff plan automatically the plan must be compatible with the current one.
Compatible tariff plans have one-to-one correspondence between their services. This implies that the system is able
to switch plans without any human intervention, all the while keeping the useful information from service links (e.g. IP
addresses in IP traffic services’ settings).
Partially incompatible tariff plans can be also switched by the system,
but at the cost of losing the services absent in the successor plan.
E.g.: For example, consider a user having the service A attached in a
tariff plan #1, and the next tariff plan set to #2, which contains the service
B. In order to transmit all parameters of the service A correctly, it is
necessary for the services A and B to be derived from the same parent,
i.e. service template.

Services
A service is a very basic object of tariffication that defines its rules.
Interface dealing with services is described in Administrator’s interface: Services on page 48. Users are linked to
services via service links (see Creating service links on page 105). Service links may be created either manually (one
by one), or in a bunch via tariff plans.
All the services have the following common parameters:


18
Services 

– Service ID;
– Service name (a mandatory parameter);
– Comment;
– Sort of service;
– Service type;
The sort of service determines the area where it is applicable. supports the following sorts of services:
– Common services;
– Tariff plan services.
The type of service determines the rules of tariffication applicable to this service. supports the following types of
services:

Type Meaning
1 One-time service
2 Periodic service
3 IP traffic service
4 Hotspot service
5 Dialup service
6 Telephony service
7 IPTV service
8 Video on demand service

Services of any particular type may have their specific parameters (see Types of services on page 20). The
tariffication logic may also be type-specific.
The service costs as entered in the interface are the before-tax values. Tax rates, including the value-added tax (VAT)
and sales tax, are specified separately in the user account properties and considered in all charge-offs.
All services except for One-time services have the start date and end date among their parameters. Start date is the
date when the service provision and fee charges start. Start date is not used in the current release of UTM5. End date
is the date when the providing of service stops, together with the charge-offs for the service. At this date the service is
removed, if it is not attached to any service link.
The following types of service:
– IP traffic,
– Dialup,
– Hotspot,
– Telephony
– IPTV
have periodic portion of the cost as one of their parameters. The corresponding charge-offs are made in a similar
manner to those for a periodic service, while the reports refer to them by their respective types of service.

Sorts of services

Common service;
Common services are intended to be applied to some users in circumstances not provisioned by the tariff plan. For
example, it may be a one-time service “Equipment setup”.
Common service;


19
Services 

– created directly;
– able to produce an arbitrary number of service links;
– never included in a tariff plan.

Tariff plan service

Tariff plan services are intended solely for inclusion in tariff plans.
Tariff plan service
– never created directly (rather, it is created as a child entity to some of the existing service templates);
– always included in a tariff plan;
– able to produce only a certain number of service links, limited by the number of tariff links.
The only unique parameter that sets apart tariff plan services from common services is the Attach by default
parameter. If this option is set, a prompt to create a service link attached to this tariff plan service will be issued on
creating manually the tariff link attached to this plan. Also, on automatic creation of such a tariff link (typically, at the
end of the accounting period) the service link will be created automatically as well, with all its parameters set to defaults.
If Attach by default is not set, the service link will not be created.

Service templates
Service templates (in earlier versions of sometimes referred to as “fictive services”) are used as the parent entities that
produce the tariff plan services on their creation and on automatic switching of tariff plans.
A service template is:
– created directly;
– not used in the tariffication logic; not a service by itself, i.e. is never attached to a service link;
– never included in a tariff plan, but acts as a parent to those services which are.
The interface for creation of service templates and operations with them is described in Administrator’s interface:
Service templates on page 55.
Ideally, there should be one service template for each logical class of services, like:
– one for the services with periodic charges;
– one for the Internet traffic using a real IP address;
– one for the general Internet traffic;
– one for the Internet users in a separated address space, etc.
Each of these service templates should have the parameters most appropriate for the particular logical class of
services. These parameters will be copied by default to the derived tariff plan services, once those are created.

Types of services

One-time service
One-time service is normally intended to perform a single charge off the user’s account. The charge-off time is
determined by the service link parameters. Price of service may be set to negative value, effectively turning the
charge-off into a contribution. The time of charging is determined by service link parameters. The service may also have
a special parameter that requests for the exclusion of the user from some given group simultaneously with the
charge-off.
Interface for creating a one-time service is described in Administrator’s interface: One-time service on page 49; for
the corresponding service link, see Administrator’s interface: One-time service link on page 91.


20
Services 

Periodic service
Periodic service is intended for periodic charges off the user’s account. The charge-off may be applied in a variety of
ways: at the beginning of an accounting period, or at the end, or in smaller portions throughout the whole period. The
price to be charged in the initial period may be corrected depending on the service link parameters, and the price of
the current period may depend on the user account’s parameters and/or blocking options.
Interface for creating a one-time service is described in Periodic service on page 49; for the corresponding service
link, see Periodic service link on page 91.

IP traffic service
Services of this type are intended for tariffication of IP traffic. The price may depend on time and on the amount of traffic
consumed. The service may contain so-called prepaid traffic, i. e. some limited amount of traffic that is passed through
without payment. Also, maximum limits for traffic (so-called quotas) may be set up to block the user after the given
amount is exhausted.
Interface for creating a one-time service is described in IP traffic service on page 50; for the corresponding service
link, see IP traffic service link on page 93.

Hotspot service
Services of this type are intended to tariff hotspot access charged per time. The authorization may be done by means
of RADIUS protocol (if supported by the hardware) or via the web interface. Different prices may be set for various time
ranges.
Interface for creating a one-time service is described in Hotspot service on page 51; for the corresponding service link,
see Hotspot service link on page 95.

Dialup service
Services of this type are intended to tariff dial-up access charged per time, possibly with different prices for various time
ranges.
Interface for creating a one-time service is described in Dialup service on page 52; for the corresponding service link,
see Dialup service link on page 95.

Telephony service
Services of this type are intended to tariff phone calls charged per time. The call price may depend on time and call
direction, and may include fixed connection price. Prepaid time option is also available. Either the caller or the called
number must be registered in the properties of the telephony service link, otherwise the tariffication is impossible.
Interface for creating a one-time service is described in Telephony service on page 53; for the corresponding service
link, see Telephony service link on page 95.

IPTV service
A services of this type isd intended to tariff IP television services. It let’s one grant access to the IPTV content for a client
and charge the client’s personal account with a periodic fee.

Video on demand service

A service of this type is intended to tariff video on demand (VoD) services. It allows one to temporarily grant access to
VoD content and charge the client’s personal account with the rent amount.


21
Charge policy 

Charge policy
The charge policy is a set of rules that are used when charging a user account. These rules are applied when a client
for some reason didn’t receive the service for some part of the accounting period. This is possible when creating a
service link in the middle of an accounting period (when the client will receive the service only for the rest of the
accounting period), or when a client uses voluntary blocking (when the client’s account was already charged with the
periodic part of the service cost).
The charge policy allows one to charge the client for the correct amount of money
according to the part of the accounting period that he actually was using or is going to use the service (for more
information on how it is calculated Periodic cost component recalculating rules on page 22).

The cost of a service is not only influenced by the cost that is set when creating it, but is influenced by the charge
policy.

Along with the cost of services the charge policy allows to correct the service parameters such as the amount of prepaid
traffic or the amount of free minutes (for dial-up service).

Periodic cost component recalculating rules

UTM5 uses the following rules for recalculating the periodic part of the service cost:
Service link start time and
date (in the future)

Service link start time

and date (in the past)
The accounting period
end time and date
Current time
Accounting period start and date
time and date

l1

l2

L
(accounting period)

The time and date of the service link creation may not match the current time and date and may be set in the future or
in the past. If the date and time of the service link creation is set in the past, the current date and time is used instead.
This means that:
Recalculated price = (Full price for accounting period) × l1/L, if the starting date has been set in the future, or otherwise
Recalculated price = (Full price for accounting period) × l2/L.
The same rules are used to recalculate the amount of prepaid traffic or prepaid calls duration.

Recalculation on block
The current UTM5 version has three types of blocking - administrator’s, system and user’s block.
– Administrator’s block is triggered by the administrator when the user’s account needs to be blocked manually.
– User’s block is triggered by the user when he doesn’t plan to use the service for some time (e.g. going on vacation).
– System block is triggered automatically when the user’s account balance becomes negative. Or, in a certain setup,
when the user’s account doesn’t have enough cash balance for charging it with the periodic fee.
For each blocking type the charge policy allows one to set up the following parameters:


22
Repay 

– do not charge periodic fee when the account is blocked

– recalc periodic fee when the account is blocked
– decrease prepaid traffic when the account is blocked
– recalc prepaid telephony when the account is blocked
When recalculating the amount of prepaid traffic, prepaid calls or the periodic fee, it decreases corresponding to the
part of the accounting period during which the account was blocked. Therefore if a user account is blocked and then
is unblocked in the next accounting period, recalculation will take place twice.

Repay
One may need a repayment when an account was excessively charged. E.g. when a user’s account was charged with
a periodic fee for the whole accounting period and during the period user decides to trigger a voluntary blocking.
The charge policy allows one to set up when exactly does the repayment take place:
– On block expire
– On payment
– On charge period end
– On remove service link

System block settings

The charge policy settings also include the settings for the system block.
If an account’s balance is not enough to charge it with the periodic fee for the next accounting period, the system block
will occur. The charging policy allows one to set up the system blocking to trigger before or after charging user’s
account. This can be set up separately for each user’s service link.

The periodic fee may be adjusted in the service link properties.

Periodic fee charges are done for several services is done in an arbitrary order. If personal account is blocked after a
charge for one of the services, charges for the remaining services are done according to the charge policy for accounts
in system blocking.

Time ranges
A time range is a set of periods of time. Time ranges are used for setting up dependency of a service cost on time and
date. For instance, to arrange lower tariffs at night time, one has to create a time range with time limits of 2:00 a.m. till
8:00 a.m., Sunday till Saturday, then create a separate traffic class and relate the new time range to it, and finally to
create a service including this traffic class and assign this service to the users.
Interface for working with time ranges is described in Administrator’s interface: Time ranges on page 55.

Coefficient scheme
Coefficient scheme is a sequence of coefficients, applied to the periodic service fee. This scheme allows one to
schedule service cost variations.
E.g. make service cost 50% for the first month, 100% from second to sixth, then 75% for the seventh month and 100%
after that. In this case one will need two coefficients in the scheme: for the first month - a 0,5 coefficient and a 0,75
coefficient for the seventh. Service cost for periods that aren't covered with scheme coefficients, is 100%.
A coefficient schemescheme may be added when creating or editing a service (see Administrator’s interface:
Periodic service on page 49).

If at least one service link is connected to a service, one can't change its coefficient scheme.


23
Currencies 

Coefficient schemes management interface is described in Administrator’s interface: Coefficient schemes on

page 56.
A coefficient scheme may be edited in the following ways: one may add or remove coefficients edit their values and
update their validity periods. An updated coefficient scheme will be used for new service links and won't affect any of
existing service links (see Periodic service link on page 91).

Currencies
A Currency is a currency unit, used by the system. NetUP UTM5 UTM5 may work with any number of currencies. All
personal accounts and charges are made in internal conventional units, so the actual currencies are only used for
payment processing and billing. When a payment is processed, the payment currency is converted to internal units.
On the other hand, when a bill is issued, the internal units are converted to some currency.
A currency is characterized by its identifier, short name, full name, and the exchange rate (regarding standard unit and
discretionary interest coefficient, which multiplies the official rate to get the provider’s internal rate). The history of
exchange rate since the system’s deployment is also available in order to perform financial operations post factum. The
exhange rate may be updated online from a variety of providers.
Interface for handling system currencies is described in Administrator’s interface: Currency on page 58.
Each user is associated with some preferred currency for billing. By default, it is defined by the system_currency system
parameter (see Administrator’s interface: Parameters on page 67). NetUP UTM5 The preferred currency may be
changed at any moment. As a result, all bills will use the newly selected currency, no matter where they created before
or after its selection.
See : Other on page 35for setting the user’s preferred currency.

Payments
There are several ways to make a payment, including:
– automatic payment via e-payment systems;
– automatic payment via any third-party software using the utm5_payment_tool utility;
– manual payment by an administrator, dealer, or cashier via the UTM Control Center.
Manual payment is made by an administrator or other operator via the Payment page of the administrator’s interface,
which may be called by the New payment from the list of users or from the user details window.
In the payment dialog the operator enters the sum of payment, currency, payment date, and probably some other data.
In particular, one of the optional parameters is the number of internal or external billing document which is the reason
for the payment.
There is an option to define whether the Internet should be switched on for the account, in case if the account balance
after the payment allows that. If not checked, then Internet status would not change on payment.
A payment may be provided with the expiration date. These are called expiring payments and summed up in a separate
report. If an expiring payment has not been spent till its expiration date, i. e. if the sum of charges since the payment
date is less than the payment sum, then the rest of the sum is expired (gets withdrawn from the client’s account).
However, if more expiring payments come in before the expiration date, the expiration of all these payments is
postponed till the latest of their expiration dates.
There is a special payment method called credit. Such payments are displayed in the user account balance under
special category and are obliged to have the expiration date, on which they are undone. When undoing a credit
payment, the total credit of the given account is checked, and if it is about to turn negative after withdrawal, the sum
of withdrawal is decreased so as to adjust the total credit to zero. Total credit of an account may also be set manually
to arbitrary value by the administrator (see : Loan on page 89).
The interface of making payments is described in Administrator’s interface: Payment page on page 88.


24
Documents 

Payment rollback
UTM5 billing system has an option of payment rollback. Payments can be rolled back by an administrator or an operator
via the UTM5 Control Center. Nominally, the rollback is done by making a payment of special method (Rollback) having
the opposite sum.
The rollback procedure is not applicable to the expiring or credit payments.
Rolling back is done via the context menu in the report on payments, see Administrator’s interface: Report on
payments on page 63.

Documents
The system contains several kinds of documents:
– User info sheet;
– Contracts;
– Receipts;
– Invoices;
– VAT invoices;
– Certificates of completion;
– Bill details.
The documents are automatically generated from templates (see Document templates on page HIDDEN).
Generated documents except for contracts are not stored in system, and are rather generated immediately before use.
User contracts may be generated using a template or uploaded from a file. Each generated or uploaded contract is
stored in user properties on the Documents page.

Invoices
Invoices for services are summarized in a special report on the Documents page of the administrator’s interface (see
Report on invoices on page 64). Invoices may be created either automatically or manually. Manual invoices have no
effect on the user’s account balance.
An invoice for a one-time service is issued immediately upon attachment of the service. If the user’s account has its
Payment in advance option checked (see : Main parameters: on page 34) and the service’s charge method is set
as At the beginning of the period, the invoices for the periodic services and for the periodic portion of special services’
price are issued at the beginning of an accounting period. Otherwise they are issued at the end of an accounting period.
Items in the automatic invoices are aggregated by tariff links (with the exception of telephony services, if any, which
remain separated from the rest) and by accounting periods. Charges for the new services (those added during the
current period) are also not aggregated and stay in a separate invoice, if Payment in advance is checked.
After having been generated from a template, an invoice may be edited for printing, but the changes can not be saved.
Invoices with negative VAT rate are hidden in the report.

IP addresses
Multiple kinds of system objects contain subnet address (i.e. an IP address with a mask) as one of their properties. As
a rule, an IP address and a mask are entered in the administrator’s interface via one common input field as
<address>/<number of significant bits>. If no mask is entered, this is interpreted as an extremely narrow
subnet consisting of single address.
UTM5 supports both IPv4 and IPv6 address formats. IPv6 addresses should be entered in the standard
colon-separated form, with possible omission of consecutive zero sections. For example, 2001:db8::ae21:ad12 is the
equivalent of 2001:0db8:0000:0000: 0000:0000:ae21:ad12.


25
Getting License Key 

Installation and Initial Setup 7

Getting License Key
In order to get a license key, login to the Customer area: https://www.netup.tv/en/utmoffice , go to the License keys
section and fill in the request form that is available once you've purchased a license.

Once you fill the form, click Send. If the request is processed successfully, UTM5 modules activation form will appear.
Each available module has an Activate button. After pressing it a icon appears (Activated). Activate all the needed
modules and press to download the key (reg.sql).

When new modules are purchased, one has to activate the license once more and to download the new license key.
Starting with version 5.3-004 a new parameter - max release date is introduced to the license. This parameter
determines the date till which the license is valid for installing and operating new UTM5 builds and updates. The release
date is set for a UTM5 installation package and remains the same for all it's updates that will be issued since the
release. E.g. the 5.3-004-release and the 5.3-004-update10 packages share the same release date. In order to install
builds and updates with a release date greater than the one in the license key, one has to update the release date and
generate a new key in the Customer area on the https://www.netup.tv/en/utmoffice . In order to do that, one must
have a valid updates subscription or a technical support subscription. When the license expires, the UTM5 core won’t
start.
If the system is installed without a license key, it will operate in demo mode with certain restrictions.
Restrictions for every module are shown on the License page of the administrator’s interface (see : Licenses on
page 88)


26
Installing Basic Components 

Installing Basic Components

Installation requirements
UTM5.3-004 requires a server with 64-bit Linux (Debian Jessie (recommended) / Wheezy, CentOS 5/6/7) or FreeBSD
10.1 / 10.2 / 10.3. It also requires a MySQL (recommended) or a PostgreSQL database server. Data Base Management
System (DBMS) may be installed on a separate server. We recommend using MySQL with InnoDB support to ensure
maximum reliability and integrity of stored data.

Using SELinux with default settings may prevent normal operation of certain UTM5 components (e.g., User Web
Interface). Be sure to carefully setup SELinux or disable it

Be sure to check the server’s date and time settings (including time zone), before installing UTM5. Otherwise, the billing
system may not function properly.
In addition to disk space required for installation UTM5 requires extra space for raw traffic data and system logs
storage.

After installing UTM5 one should install the User Web Interface (see Web interface: Installation on page 177).
It will require Apache Web server for proper operation

Installation Procedure
1. Installing UTM5-3.004 package:
– on Debian, run the following command: :

dpkg -i utm5-3.004.deb

If any library specified in the installation package dependencies is missing, the OS will display the corresponding
message and interrupt the installation process. In that case, run the following command: apt-get install
-f. 
The OS will automatically download and install all the required libraries and then resume the installation.

– on CentOS, run the following command (V is for CentOS version: 5, 6 or 7) :

yum --nogpgcheck localinstall utm5-3.004.x86_64-centosV_x64.rpm

– on FreeBSD, run the following command:

pkg add utm5-3.004.tbz

Installation on FreeBSD may require additional libraries: openssl, libxml2.

The installer will create /netup/ directory to store program data, configuration and log files. It will also create the
following startup scripts:
– on Debian and CentOS:
* /etc/init.d/utm5_core
* /etc/init.d/utm5_radius
* /etc/init.d/utm5_rfw
* /etc/init.d/utm5_dhcp
* /etc/init.d/utm5_traffic_collector
– On FreeBSD or Solaris:


27
Updating to version 5.3-004 

* /usr/local/etc/rc.d/utm5_core.sh
* /usr/local/etc/rc.d/utm5_radius.sh
* /usr/local/etc/rc.d/utm5_rfw.sh
* /usr/local/etc/rc.d/utm5_dhcp.sh
* /usr/local/etc/rc.d/utm5_traffic_collector.sh
2. Examining UTM5 core configuration:
We strongly recommended to check and (if necessary) edit the /netup/utm5/utm5.cfg file BEFORE starting
UTM5 core for the first time. In particular, be sure to check the database (DB) interaction parameters.
For detailed configuration file description please refer to System core: Configuration file on page 114.
– If planning to use an existing DB, be sure to check the utm5.cfg DATABASE section parameters (e.g., DB type,
name, charset, login, password, etc.).
– If the database does not exist, UTM5 will automatically create it at first startup. Consider that the database will use
the parameters set in utm5.cfg.
– Check and edit the configuration if necessary. UTM5 core may perform DB structure/indexes update and archived
tables verification at each start. This is controlled by the utm5.cfg verify_database,
verify_database_index parameters. By default, DB structure check is enabled, indexes check is disabled

The DB user account used by UTM5 must have privileges for creating and modifying databases and tables

3. Starting UTM5 core. 

After successfully installing the UTM5-3.004 package, and setting all the required configuration file parameters to
appropriate values, copy the license key file reg.sql to /netup/utm5/ directory and start the UTM5 core with
the following command:
– on Debian and CentOS:

/etc/init.d/utm5_core start

– On FreeBSD or Solaris: 

/usr/local/etc/rc.d/utm5_core.sh start

At startup UTM5 core will import license information from /netup/utm5/reg.sql and delete the file. Then the
core will try to connect to a database using utm5.cfgDATABASE section parameters. If the DB specified in the
configuration file does not exist, UTM5 will try to create it.
4. For CentOS only. In order to make UTM5 core start automatically after OS boot-up, execute the following
commands (root privileges required):

chkconfig --add utm5_core

chkconfig utm5_core on

Other UTM5 modules may be added to the autorun list in a similar way.

On Debian and FreeBSD, UTM5 installer automatically adds modules’ startup scripts to the autorun list

Updating to version 5.3-004

Installation requirements
When upgrading from UTM5 version 5.3-001-update6 or older, we strongly recommend that you read earlier update
guides and changelogs (please refer to UTM 5.3-002 upgrade to version 5.3-003 user manual in Documentation
section at https://www.netup.tv/en/utm5/documentation ).
Please refer to OS compatibility for the UTM5.3-004 compatible OS list.


28
Updating to version 5.3-004 

In order to avoid any dtagg_iptraffic table automatic data conversion issues, set the max_allowed_packet
MySQL settings parameter to 32M or greater.

Update Procedure
1. Stop all UTM5 components (i.e.,UTM5 core, RADIUS server, DHCP server, etc.). For example in Linux execute the
following command to stop UTM5 core: 

/etc/init.d/utm5_core stop

Then make sure that the service actually stopped. For example, execute the following command to check if UTM5
core is running:

ps ax | grep utm5_core

2. Back up all configuration files from /netup/utm5/

3. Be sure to create a fresh backup of the SQL DB and detailed traffic information (one can use mysqldump or
pg_dump utilities, depending on DBMS type), or use an existing backup if it is up-to-date. Make sure all the data
can be restored from that backup.
4. Remove old UTM5 installation. On Debian, execute the following command: 

dpkg -r utm5

On FreeBSD, run: 

pkg delete utm5

On CentOS, run:

yum remove utm5

5. Install the new version of UTM5. On Debian, execute the following command: 

dpkg -i utm5-3.004.deb

If any library specified in the installation package dependencies is missing, the OS will display the corresponding
message and interrupt the installation process. In that case, run the following command: apt-get install
-f. 
The OS will automatically download and install all the required libraries and then resume the installation.

On FreeBSD, run: 

pkg add utm5-3.004.tbz

Command for CentOS (V is for CentOS version: 5, 6 or 7):

yum --nogpgcheck localinstall utm5-3.004.x86_64-centosV_x64.rpm

6. The new version of UTM5 core will automatically update the DB structure at first launch (provided that the
corresponding utm5.cfg parameter is enabled). The DB user account used by UTM5 must have privileges for
creating and modifying databases and tables.
One can also update DB structure manually. For example, if using MySQL, execute the following command : 

mysql -f UTM5 < /netup/utm5/UTM5_MYSQL_update.sql

If using PostgreSQL, execute the following command:

psql -f /netup/utm5/UTM5_PG_update.sql -d UTM5


29
Updating to version 5.3-004 

7. In order to automatically update DB indexes at first launch, add the following parameter to the UTM5 core
configuration file (utm5.cfg): 

verify_database_index=enable

This operation may take some time to complete.

One can also update DB indexes manually. For example, if using MySQL, execute the following command: 

mysql -f UTM5 < /netup/utm5/UTM5_indexes.sql

If using PostgreSQL, execute the following command:

psql -f /netup/utm5/UTM5_indexes.sql -d UTM5

This operation may take some time to complete In order to minimize idle time, one might use Table archiving
function before updating the database indexes function.

By default all archived tables structure is checked for compliance with UTM5 core requirements. If
utm5.cfgverify_archive_tables parameter is enabled, UTM5 core will attempt to bring the tables structure in line
with the requirements. If successful, the archived data will be used when generating reports. Otherwise, the
system will ignore the information from those archived tables.

8. Starting with version 5.3-004, license determines availability of UTM5 updates. Be sure to visit the Customer Area
at https://www.netup.tv/en/utmoffice and update the license prior to upgrading to 5.3-004. Then, download the
updated reg.sql file and place it to /netup/utm5/ directory BEFORE the first start of the updated UTM5 core.
At first start the updated core will import the license information from netup/utm5/reg.sql and delete the file.
License renewal is also required in case of purchasing any additional UTM5 modules and/or services.

Be sure to update the license before upgrading to version 5.3-004! Otherwise, the updated UTM5 core will not
start.

9. Launch the required UTM5 components.

All UTM5 components must have the same build number. When using multiple servers running different UTM5
components, be sure to update all the components to the latest UTM5 build. Components from different UTM5
builds may not interact properly.

For example, on Linux, run the following commands to start UTM5 core and DHCP module:

/etc/init.d/utm5_core start
/etc/init.d/utm5_dhcp start

10.Document generation system implemented in UTM5.3-004 is incompatible with the system, implemented in
versions older than 5.3-003. Please refer to the current UTM5 documentation to get familiar with the new document
generation system, and update all document templates to comply with the new format. In order to generate
documents in PDF format, LibreOffice package is required to be installed on the server running UTM5; otherwise,
the documents will be generated in ODT format.


30
Introduction 

Administrator’s interface 8
Introduction
UTM5 control center is a program used to control user accounts and billing system settings. Examples of use are given
in Usage examples on page 99.

The interface version must be the same as the UTM5 core version, otherwise the interface may function
improperly.

Top-level menu is described in Menu. General interface features and common principles are described in Common
features (page 32). The basic interface pages are accessible via the links in the left pane which are grouped in the
following sections:
– Users and groups (page 33);
– Messages (page 41);
– Tariffication (page 42);
– Reference book (page 58);
– Reports (page 59);
– Settings (page 67);
– Interfaces (page 81);
– Additional Features (page 85);
– Inventory (page 85)
– About (page 87).
Depending on the settings and permissions of the particular operator, some pages may be hidden and inaccessible. If
all pages in some group are hidden, the group itself is hidden too.
The pages which are accessible neither directly from the left pane nor from the basic interface pages with standard Add
/ Edit buttons are described in Stray pages (page 88).
Once started, the program is represented by an icon in the system tray (see Tray icon on page 176).

Menu
Below is the description of the program’s top-level menu.

System
– Reconnect – stops the control center and opens the connection window (see Usage examples: Installation and
startup on page 99).
– Import – opens the Import window (see Structured data import on page 158).
– Exit – closes the control center.

Settings
– Settings – opens the edit settings window. Contains the following settings:
– UsersPerPage – is the number of users per one page as shown in the list of users (see Users on page 33);
– CSVSeparator – is the separator selection for exported CSV files (is one of the following: comma or a
semicolon);


31
Common features 

– TurnInternetOn – is the default setting of Internet status switch for newly created accounts;
– NotVPN – is the default setting of Not VPN IP group flag for newly created IP groups;
– DoNotAffectFW – is the default setting of Do not affect firewall rules flag for newly created IP groups;
– UseCustomPassword – is the flag to use custom set of symbols to generate passwords for newly created users;
– CustomPasswordCharset – is the set of characters used to generate passwords for new users, once the
UseCustomPasswordoption is checked;
– CustomPasswordLength – is the generated passwords’ length, once the UseCustomPasswordoption is
checked;
– DoubleRounding – is the number of digits after the decimal point to which all the output sums are rounded;
– HousesPerPage – Is the number of houses per page;
– FirstTime – is the flag of running the program for the first time;
– Language – is the interface language;
– SavePassword – is the flag that controls whether or not to save the password;
– SaveSettings – is the flag that controls whether or not to save the settings.
– Shortcuts – opens the Shortcuts window for setting hot keys to various typical activities. This window contains the
following tabs:
– Main window – contains shortcuts for the pages available in the side menu of the main window of the
administrator’s interface;
– User – contains shortcuts for the pages available in the side menu of the edit user window;
– Dealer – contains shortcuts for the pages available in the side menu of the main window of the dealer’s interface;
– Service – contains shortcuts for the service setup pages;
– Time zone – selects the time zone from the drop-down list.
– Messages – sets up the message preview options (see Messages on page 41).

Normally, time zone is imported from the OS settings while installing UTM5.

Help
– About – displays the version info.
– Contents – opens NetUP UTM5 help.

Common features
The basic interface pages contain lists of entities (users, services, etc.) with a number of features for each entity.
Mouse right-clicking on the list reveals a context menu that contains a number of handy commands including Edit,
Remove (once the operator has sufficient privileges), Refresh, Columns, and probably also some commands specific
to a particular type of entities.
Columns of the tables can be reordered by drag-and-dropping. Their width may also be adjusted by dragging the
column borders. The representation of particular columns may be switched on or off via the context menu item named
Columns. As a rule, the default settings imply that all possible columns are displayed.
Entries in the list may be ordered by any column via clicking on the column header. Repeated clicking on the same
column header reverses the sort order.
Multiple selection of list items may be performed by left-clicking with pressed Shift (selects a range of entries) or Ctrl
(selects multiple entries one by one). Pressing Ctrl + A selects all entries on the page.
The Export item of the context menu exports the list in the CSV or XML format, considering the current column display
settings.


32
Users and groups 

Depending on the purpose of the page and the user’s rights, the page may contain an interface for addition, editing or
removal of its elements in a form of buttons Add, Edit, and Delete. Some of the buttons may be disabled due to the
insufficient access rights. In case of view-only access the Edit button is substituted by Read. As a rule, the addition or
editing of an element is performed in a separate window. The corresponding form may or may not have the
button which resets all its fields at once.

The button refreshes the list to reflect possible changes that could have been introduced by another
administrator in the meantime, or could have occurred automatically.
The top menu (see Menu on page 31), the left pane with quick links, and the bottom status line displaying current server
time are visible and accessible from any interface page.
In case if the connection to UTM5 core is lost, focus switches from the main window to the pop-up window with
Reconnect button.

Users and groups

Users
This page contains the list of users (see Basic system objects: Users on page 15) with the interface for creating,
removing, editing a user, or making payment.
– User ID – of the user.
– Login – is the user’s login.
– Primary account – is the account number.
– Full name – is the full name of the user or a title of the legal entity.
– Blocking type; – is the blocking status of the user.
– Balance – is the account balance.
– IP (VPN) and IP (non-VPN) – are the lists of user’s networks set in the properties of IP traffic service links.
Page contains the following interface elements:

– button opens the user creation window (see Adding users on page 34).

– buttons open the user details window similar to that of a regular user, i.e. containing the following
page groups: User (page 34)Tariffication (page 35), and Reports (page 36).

– button removes the selected card user(s), once the related service links and tariff links are removed, or
displays an error message otherwise.

– button opens the search window (see Search page on page 89).

– button opens the payment window (see Payment page on page 88).
Context menu of the list of users contains quick links for the following operations with the selected user(s):
– Switch Internet on;
– Switch Internet off;
– Make a payment.


33
Users and groups 

Unlike the majority of other lists, the list of users is displayed pagewise, with the page number and the number of users
per page set in the bottom part of the page. These settings are persistent, i. e. once set, they are saved and resumed
on the next launch of the program.

List entries are marked with color. Red means that the user’s accounts are blocked, green means they are not, and
yellow means that some accounts are blocked, while others are not.

Adding users
The Add user window contains the following pages:
– Main parameters: – includes login, full name, password, and the Payment in advance check box. Login name
must be unique and consist of the following symbols: lowercase latin letters (a-z), numbers (0-9), dots, commas,
“@”, “_”, “-” and “/”. One may choose to generate a random password, which is then automatically substituted into
the Password and Confirm password fields, and shown openly in the Generated password field for copying. This
login:password pair is used solely for the access to the user interfaces (see and ). 
This “login: Password” pair is only used to access the user interface (see utm5_tray utility on page 173and Web
interface on page 177).
– Additional parameters – includes bank account details and some other data, including custom parameters (see :
Additional parameters on page 69).
– Contacts – includes user’s personal data (address, phone, e-mail).
– Other – other user associated parameters: documents profile remote switch address, port, and preferred currency.
For more information about document profiles see Document profiles on page 76.

User
The User group in the user properties window includes the following pages:

– Main parameters: – includes login, full name, password, and the following elements:


34
Users and groups 

– Payment in advance check box (if checked, the invoices for the periodic services with charge method set as At
the beginning of the period are issued at the beginning of the accounting period; has no effect on charges);
– Generate document for user button that displays the handout document for the user containing login, password,
and the provider’s contact information;
– Link to dealer button that opens the interface to link this user to one of the existing dealers (see Dealer module
on page 166).
– Additional parameters – includes bank account details and some other data, including custom parameters (see :
Additional parameters on page 69). Bank details may be filled in automatically by linking the user to a bank (see
Banks on page 59).
– Contacts – includes personal data (address, phone, e-mail) of the contact person. The address may be filled in
automatically by linking the user to a house (see Buildings on page 59). 
Also, this page contains the Send invoices by email check box that gets active once an e-mail is entered.
– Additional contacts – includes personal data of additional contact persons, if any.
– Groups – is the list of groups the user belongs to, together with the interface to add the user to a group or remove
from it.
– Other – are special parameters associated with the user, including document profile, remote switch address, port,
and preferred currency. For more information about document profiles see Document profiles on page 76.
– Documents – is the list of documents for the user, together with the interface to generate, edit and delete them.
Documents may be generated from templates (see Document templates on page HIDDEN), or may be uploaded
as *.odt files.

Any *.odt file may be uploaded as user document.

– Additional info – is the view-only auxiliary information (dates of creation and last modification of the user).

Tariffication
The Tariffication group in the user properties window includes the following pages:
– Accounts – is the list of the user’s accounts containing the interface to create, edit, and remove the accounts, as
well as to make payments.
Creation and editing of an account is performed in a special window (see Personal account on page 89).
For usage examples see Creating account on page 103and Removing an account on page 103.

To change the blocking settings of an already blocked account, it is necessary to lift the existing blocking and
then impose it again with new settings.

Right click one of the listed accounts to open the context menu. This menu, along with standard elements, contains
the following:

– Switch Internet off – switches off Internet for the selected account
– Balance correction – allows one to correct balance for the selected account.
One can also add a comment for this action. Balance correction operations and comments for these operations
get to the User Change Log report.
– Service links – is the list of the user’s service links together with the interface to create, edit, and remove them, also
containing the following interface elements:


35
Users and groups 

– Prepaid traffic – sets the prepaid traffic (active if the item selected in the list is an IP traffic service link);

The amount of prepaid traffic can't be reduced. It can be increased, but consider that the final amount is
calculated by adding new amount to the initially set value, or to the remainder, if part of the initially set prepaid
traffic had been consumed. E.g. 150 Mb of prepaid traffic is left and one wants to add 100 Mb. In this case one
should set the amount to 100. In case one wants to add another 100 Mb, she should add 200, because this
amount would be added to the initial 150 Mb.

– Set RADIUS parameters – sets the RADIUS attributes for the selected service link;
– Select account – is the drop-down list to select one of the user’s accounts.
Creation and editing of a service link is performed in a special window (see Service link on page 91).
For usage example see Creating service links on page 105.
– Tariff links – is the list of the user’s service links together with the interface to create, edit, and remove them, also
containing the following interface elements:
– History – displays the history of tariff plans previously associated with the user;
– Select account – is the drop-down list to select one of the user’s accounts.
Creation and editing of a service link is performed in a special window (see Tariff link on page 90).
For usage example see Creating service links on page 105.
– Technical parameters – are the arbitrary parameters associated with the user. Their values may be used in the
commands for controlling the external software, which are sent by as a response to certain events, see UTM5 RFW:
Firewall rules on page 138.
– IPTV activation codes – is a list of activation codes for an access card, assigned to the selected personal account.

Reports
The Reports group in the user properties window includes the reports of various types for the selected user, each on
a separate page. The interface is similar to that on the general reports page (see Reports on page 59), except for the
following details:
– Group selector is missing;
– On all pages, except for Detailed Traffic, Graphic Report and User Change Log, there is a drop-down list to select
one of the user’s accounts, or all accounts.
– On the Documents page, on the Invoice tab there is a New invoice button.
The following types of reports are included:
– General – is the report on payments and charge-offs of all types;
– Blockings – is the report on blockings of the given user;
– Traffic – covers the consumption of traffic by classes;
– Telephony – contains the statistics of phone calls;
– Telephone directions – contains aggregated statistics of phone calls by directions;
– Sessions – contains the statistics of dialup and VPN sessions;
– Payments – contains the statistics of payments to the user’s account(s);
– Services – contains the statistics of services;
– Other charges – lists the charges not related to any services (payment expiration, rollback, etc.);
– Internal transfer – lists the transfers of funds between one’s accounts, which the users may perform on their own;
– Detailed traffic report – covers the traffic consumption in full detail, with source and destination addresses and port
numbers;
– Documents – contains the statistics of invoices. The Invoice tab also contains the New invoice button, which
allows creation of an invoice with arbitrary positions;


36
Users and groups 

– User Change Log – covers the changes in the user’s data;

– Report on expiring payments – contains the statistics of expiring payments;
– Graphic report – contains the reports on some services (IP traffic, dialup, telephony) in a graphic form;
– Custom charges report – lists the charges performed by third-party systems via UTM5 integration modules.
– DHCP lease – lists the history of DHCP leases in selected time range.

Card users
This page contains the list of card users, which are the users generated automatically on registration of prepaid cards
on the automatic registration page of the web interface (see Web interface: Entrance page on page 177). Card users
are not supposed to be created manually. Page contains the following interface elements:

– buttons open the user details window similar to that of a regular user,

– button rremoves the selected card user(s), once the related service links and tariff links are removed,
or displays an error message otherwise.

– button opens the payment window (see Payment page on page 88).

– button removes the card users linked to overdue cards.

The interface of card generation is described in Card pools on page 39.

System users
This page contains the list of system users (see Basic system objects: System users on page 16) with the interface
for creating, removing, or editing them. When creating a system user, she can be included in one or more groups (see
System groups on page 38), which determines her privileges.

The and buttons open the system

user properties window containing the following input fields:
– User ID – of the user.
– Login – of the user in the system.

Logins of the system users can not coincide with those of

the ordinary users.

– Password, confirm password – are thepassword and its

confirmation fields.
– IPv4/IPv6 subnet – is the subnet from which the user’s
access is allowed (optional parameter). (see IP addresses
on page 25for the formatting details.)
– System groups – is the list of system groups that the current
system user is the member of. Any changes to the list of
groups take effect only after the next UTM5 core restart.

Dealers
This page contains the list of dealers with the interface for creating, removing, or editing them. Dealers are the special
entities that may perform some administrative functions over a particular subset of users.
See Dealer module on page 166for the details on dealers’ purpose, functions, creation, and operation.


37
Users and groups 

Groups
This page contains the list of user groups with interface to create, edit, and remove them, as well as to perform group
operations.
Editing of a group may include removal of users from the said group. Addition of users to a group may be performed
on the user properties page (see : Groups on page 35) and on the search page (see Search page on page 89).
Group operations include:
– Switch Internet on for all members of the selected group;
– Switch Internet off for all members of the selected group;
– Group all blocked users (i.e. all blocked users are added to the selected group);
– Set tariff plan for next accounting period for the members of the selected group having particular current value
of the next tariff plan, or for the whole group (if the value is specified as “Any”).

Each user is normally associated with some current tariff plan and some tariff plan for the next accounting period.
These two plans may or may not coincide. The selection is based upon the latter.

– Change policy for the members of the selected group that have currently active policy, selected in the Old policy
field.

System groups
This page contains the list of system groups with the interface for creating, removing, editing, or copying them. System
groups are used to set the permissions of system users (see System users on page 37).

The and buttons open the Time range window containing two tabs: Plain view and Tree
view.

Each system group has the following parameters: ID, name, comment, and the list of available functions. The latter may
be picked via any of the two interfaces:
– On the Tree view tab the visual interface is presented, with all functions grouped in the hierarchical tree by
application field. The tree is redundant, so that some low-level functions are included in multiple branches
simultaneously. On changing the permission for such a function a warning window appears with a listing of other
branches affected by this permission.


38
Users and groups 

– On the Plain view tab all functions are displayed in an unstructured alphabetic list.

The Wheel and Dealers system groups are built-in, so their properties can not be altered.

Card pools
This page contains the list of prepaid cards pools (see Basic system objects: Prepaid cards on page 17), with the
interface to add or modify them. Card pools can not be removed.

button opens the card generation window (see Generating cards on page 39). Generated cards can't be
edited or deleted.

button opens the card pool properties window (see Editing card pools on page 40).

button removes overdue cards from the selected pool(s).

button opens the cards search window, where the cards may be searched by an arbitrary combination of
conditions on card ID, pool ID, tariff ID, PIN code, card balance, currency, and the activation date.

Generating cards
Card generation window contains the following fields:
– ID – is the pool ID (if points at the existing pool, the
cards are added to it; otherwise, a new pool is created).
– Quantity; – is the number of cards to be generated.
– Balance – is the monetary value of one card.
– Currency – is the currency in which the card value is
specified.
– PIN code length – is the number of digits in the PIN
codes to be generated.
– Random numbers – switches on generation of
random ID numbers for the cards; if not set, the
numbers are issued sequentially.
– Unique PIN – requires that the generated PIN codes are unique.
– Use before – is the optional date to activate the card strictly before.
– Days – is the optional term of expiration of the payment made when the card gets activated. If not set, the payment
is not expiring.
– Tariff ID – is the optional tariff attached to the card users on registration.

The created cards may be neither edited nor removed.If the tariff for the card users contains some services with
periodic component, on user’s registration those get attached to the system accounting period, which is since
1/1/1970 till 1/19/2038. Therefore only the services with no or negligible periodic payment are suitable to include
in such tariff plans.


39
Users and groups 

Editing card pools

Card pool details window lists the cards in the pool together with their PIN codes, status info, and activation dates.

The window contains the following interface elements:

– Add – button opens the cards generation window (see Generating cards on page 39) window to add a new lot of
cards to the pool. The new lot of cards has the same parameters as a new pool.
– Refresh – button updates the list of cards.
– Export – button exports card data for this pool to an XML file.
– Block – button blocks selected cards.
– Unblock – button unblocks selected cards.
Below is the list of owners. These are the system users having the right to register users based on the cards from this
pool. The option of having different owners for various pools may be relevant when the system contains several web
interfaces run by different system users. If the list is not set, any system user has the right to register users.
The list may be altered by the following buttons:
– Add owner – add a new owner to the list;
– Delete – deletes the selected owner from the list.

IP groups
This page contains the list of IP groups defined within service links of IP traffic services (see IP traffic service link on
page 93).

Telephone numbers
This page contains the list of telephone numbers defined within telephony service links (see Telephony service link
on page 95).


40
Messages 

Messages
This page contains interface for sending and receiving system messages from the users and other administrators.
Users may send their messages via web interface (see Web interface: Messages on page 179) or via the utm5_tray
application (see utm5_tray utility: Messages on page 175). If the web_message_group parameter (see Settings
available in the administrator’s interface on page 117) is set, then the messages sent via web interface will be seen
only by the members of the system group specified by this parameter.

Messages are subdivided into the folders:

– Incoming;
– Outgoing;
– New;
– Deleted.
The Filter roll-up pane may be used to filter messages by an arbitrary set of conditions on the message parameters,
which include sender, receiver, sending time, etc.
Depending on the system settings (see : Messages on page 32), the preview pane for viewing the selected message
may be shown along with the list of messages.
The following action buttons are present:
– Add – creates a new message.
– Read – opens the selected message in a separate window for reading.
– Reply – creates a new message in a reply to the selected one.
– Forward – resends the selected message to another addressee.
– Delete – moves the selected message to the Deleted folder.


41
Tariffication 

A message may be addressed to:

– User (selected in a separate search window, see
Search page on page 89);
– Group (selected from the list);
– System user (selected from the list);
– System group (selected from the list);
– All users.

Message type may be one of the following: Plain text

and HTML.

Tariffication

Tariff plans
This page contains the list of registered traffic classes (see Basic system objects: Tariff plans on page 18) with the
interface for creating, removing, or editing them. with the interface for creating, removing, or editing them.
A tariff plan can be removed only if it is not used at the moment. Otherwise, in the first place it is necessary to remove
all tariff links attached to it.

button opens the tariff plan creation window with the

following input fields:
– Tariff name – is a mandatory parameter.
– Zero balance at the end of accounting period – is a check box
for resetting to zero the balance of the account connected to this
tariff plan by the end of the accounting period.

button opens the tariff plan properties window that

contains the following parameters:
– Tariff ID – is assigned automatically.
– Tariff name – is a mandatory parameter.
– Created on, Last modified on – are the dates of creation and the
last modification of the tariff plan.
– Created by, Modified by – are the names of the system users
responsible for the tariff plan creation and its last modification,
correspondingly.
– Zero balance at the end of accounting period – is a check box
for resetting to zero the balance of the account connected to this
tariff plan by the end of the accounting period.
– Services – is the list of services included in the tariff plan.


42
Tariffication 

To add a new service to the tariff plan, press Add. The list of existing service templates will show up. 


Select the template you need and press OK.

A tariff plan may not contain multiple services originating in the same template.

Traffic classes
This page contains the list of registered traffic classes (see Basic system objects: Traffic classes on page 17) with
the interface for creating, removing, or editing them. A traffic class can only be removed if it is not used at the moment.
Otherwise, it is necessary first to remove all tariff links attached to it. Once a traffic class is removed, the traffic belonging
to it would pass for unidentified in the control center reports (see Administrator’s interface: Reports on page 59). At
the same time, in the web interface reports (see Web interface: Reports on page 179) the removed traffic class would
continue to show up as existing.
For the example of usage see Creating traffic classes on page 101.
Below is the list of traffic class parameters and their meanings:

– ID – is a mandatory parameter. The numbers should be selected in such a way that the numbers of child classes
would be higher than that of their parent class.
– Name; – is a mandatory parameter.
– Don’t save – check box disables saving of raw traffic data files, if checked. May be worthwhile to set for the free
traffic or in other cases when the detailed information is unlikely to ever become necessary. Reduces the raw traffic
data files size.

Format of the raw traffic data files has been altered in UTM5.3-001, so that the files saved in earlier versions can
no longer be read.


43
Tariffication 

– Time range – limits the traffic class existence with the given time range, if selected.
– Graph color – is the color to represent the traffic of this class in the graphic reports.
– Display – enables display of this class in the graphic reports.
– Fill in – sets fill style for the graph reports.
Besides that, the traffic classes page contains interface for working with subclasses. The interface consists of the
following buttons.
– Add;
– Edit;
– Delete;
– Export – all subclasses of the given class as a CSV or XML file with following contents.
– CSV: each subclass is described on a single line. Properties’ values are separated with semicolons, and each line
ends with a semicolon. Names of the properties are listed in the first line.
– XML: the root tag is UTM_export. Each subclass is described in a separate instance of the row tag. Inside it there
is the tag row_id followed by the subclass properties, each wrapped in its own dedicated tag, in the same order
as in the CSV file.
– Import – imports a CSV or XML file of similar format and attaches all retrieved subclasses to the given class.

Traffic subclasses
A traffic subclass is characterized by the following
parameters:
– For the source or destination:
– Network address and mask (mandatory, may be
entered as IPv4 or IPv6, see IP addresses on
page 25for the formatting details);
– Port;
– Interface;
– AS (autonomous system number);
– Protocol;
– Next router;
– TOS (TCP/IP “type of service” field);
– TCP flags;
– Router IP.

Types (IPv4 vs. IPv6) of the source and destination addresses must coincide; type of the router IP does not have
to follow them and may be arbitrary.

If Router IP is not set, the NetFlow provider address is not considered.

If Skip is checked, the affiliation with subclass is interpreted negatively in the classification, i.e. it means that the traffic
does not belong to the given class and needs to be checked against other classes. This may be useful if some address
or a group of addresses needs to be pick out as a separate class.

Telephone zones
This page contains the list of registered telephone zones with the interface for creating, removing, or editing them.


44
Tariffication 

Telephone zone is a set of telephone directions (see Telephone

directions) joined together for more convenient tariffication of phone calls.
The cost of a telephone call may be set in the settings of the Telephony
service for any created zone taking into account time ranges.
Telephone zone is characterized by the following parameters:
– ID;
– Name;
– Type of coverage, which is to be selected among:
– local,
– inner zone,
– intercity,
– international;
– List of telephone directions included in the zone.
May be edited by Add / Remove buttons.

Telephone directions
This page contains the list of registered telephone zones with the interface for creating, removing, or editing them.
Telephone direction is a set of telephone numbers. The
attribution of a particular number to a direction is checked
by means of regular expressions. Telephone directions are
used to classify phone calls for subsequent tariffication. 

Telephone direction is characterized by the following

parameters:
– ID – is a number > 1000000 (assigned automatically).
– Zone – is the name of a telephone zone into which the
direction is included (set automatically).

Every telephone direction may be included in one and only one telephone zone.

– Type – is the call type (local, intercity, etc.; inherited from the parent zone, if it is set).
– Name – is a mandatory parameter.
Classification criteria (at least one must be non-empty):
– Called prefix – is a prefix or a regexp for checking the calling number. is a prefix or a regexp (POSIX 1003.2
compatible) for checking the called number.
– Calling prefix – is a prefix or a regexp for checking the calling number.
– Incoming trunk;
– Outgoing trunk;
– PBX ID;
– “Skip” flag – cancels identification (if checked, no calls will be identified into this direction).


45
Tariffication 

The list of directions is kept ordered lexicographically by called prefix, then by calling prefix, then by incoming trunk,
and then by outgoing trunk. The search is performed from the beginning of the list till the first match. Directions with
matching called prefix are sorted by the calling prefix in a descending order. Directions with both prefixes matching are
sorted by the incoming trunk, etc.
Search goes from the beginning of the sorted list until the first match. To be identified with the direction, a call must
match all parameters (called prefix, calling prefix, incoming trunk, outgoing trunk, PBX ID) which are set for this
direction.
It is recommended to create the default direction with called prefix ^.*$, so as to leave no number unassigned.

Accounting periods
This page contains the list of current accounting periods (see Basic system objects: Accounting periods on
page 18). with the interface for adding or editing them.
An accounting period can not be removed.
Once a period finishes, a new period of the same type is created automatically.
Below is the list of accounting period parameters and their meanings:
– Start time – is the date and time when the period begins.
– End time – is the date and time when the period ends. When
creating a new period, this field is missing, since the date is
calculated automatically.
– Period type – is selected among the following:
– daily;
– weekly;
– monthly;
– quarterly;
– annual;
– custom duration.

Monthly period ends in the next calendar month after its start, on the same day of month. However, if the starting
date exceeds the number of days in the next month (say, January 30), the period lasts only till the end of the next
month.

– Report period – allows one to link the invoices generation date to a calendar month. Is only available for a monthly
period type.
– Custom duration – is the length of period in seconds. Enabled only if Period type is set to Custom duration. The
shortest possible duration is 3600 seconds.
– Set number of charges – enables setting number of charges per week.
– Charges per week – is the number of periodic charge-offs per week. Enabled only if Set number of charges is
checked.
When an existing period is edited, its ending date is the only property that may be changed.

Charge policies
This page contains the list of active charge policies. For more information on Charge policies see Basic system
objects: Charge policy on page 22
Every charge policy contains certain rules for recalculation of periodic component of a service price, prepaid services
amount and refunding rules. I.e. it is the periodic fee, prepaid traffic and calls amount recalculation settings.


46
Tariffication 

Creating a charge policy

Press This will open a charge policy setup window.

A charge policy has the following parameters:

– Main parameters:
– Name – is the name of the charge policy
– Recalculation on service link creation – contains parameters that define which of the following will be
recalculated on link creation:
– Periodic fee – is the periodic fee
– Traffic – stands for the amount of prepaid traffic
– Telephony – stands for the amount of prepaid calls
– Don't charge without block – charge when blocked:
– Periodic fee – is the periodic fee

This condition only works if the Recalc periodic fee option is selected for the block type that is used for
blocking the user’s personal account (see Usage examples: Creating a charge policy on page 104)


47
Tariffication 

– Recalculation on block – contains recalculation parameters for different blocking types (contains the following
tabs: Administrative, User and System):

Switching to another tab preserves all the parameters for the previously chosen block type.

– Do not charge periodic fee – means that the account won’t be charged for the periodic fee while in block
– Recalc periodic fee – means that the periodic fee will be recalculated proportionally to the time spent in block
during the current accounting period
– Decrease prepaid traffic – means that the amount of prepaid traffic will be recalculated in the same way as the
periodic fee
– Recalc prepaid telephony – means that the amount of prepaid calls will be recalculated in the same way as the
periodic fee.

Note that the recalculation parameters are set when blocking starts. This means that when the blocking ends,
periodic fee, prepaid traffic and calls will be recalculated according to the charge policy parameters recorded
when blocking started, even if the charge policy parameters were changed since then.

– Repay – is a set of rules that define which event should be coupled with a customer debt repayment (when the
customer’s account has been charged excessively):
– On block expire
– On payment
– On charge period end
– On service link removal
– System block settings – has the following parameters:
– Set system block on funds lack – sets system block when an account has insufficient funds for fee withdrawal
at the beginning of the next accounting period (fee withdrawal doesn’t happen in this case). If this option is
disabled, the check is not performed. In that case if an account has insufficient funds, it’s balance will become
negative after withdrawal and the account will be blocked.
– Block timemarks – is the time for daily check of blocked account’s balance. If at some point of time there’s
enough funds to pay for the services for the rest part of the current accounting period, UTM withdraws that money
and unblocks the account. Block timemarks are only used when the first option is enabled.

Services
The Services page contains the list of registered services (see Basic system objects: Services on page 18) with the
interface for creating, removing, editing, or copying them.
A service can be removed only if it is not used at the moment. Otherwise, in the first place it is necessary to remove
all service links based on it.

Pressing opens the service properties window focused on the Main page. This page includes the following
elements:
– Name – is the name of the service.
– Comments – is an arbitrary comment.
– Type – is the drop-down list for selecting the type of service.
– Supplier to invoice – is the legal entity on whose behalf the service is provided (see Companies on page 74).
The contents and composition of other pages (see below) varies depending on the selected Type value.

On pressing , the service properties window with disabled Type field shows up.
Attachment of services to the users is normally done by means of service links created via the user properties page
(see : Tariffication on page 35).


48
Tariffication 

One-time service
One-time service properties window consists of two pages:

– Main (standard, Services on page 48).

– Service parameters. Includes the following elements:
– Cost, % – is the price of the service.
– Delete from group – is a drop-down list for selecting a group from which the user is to be excluded immediately
after the charge-off for the service.
– Contract type – comment that can be selected from a list of precreated comments. For more details see
Administrator’s interface: Contract types on page 57
Parameters of the corresponding service link are described in One-time service link on page 91.

Periodic service
Periodic service properties window consists of two pages:

– Main (standard, Services on page 48).

– Service parameters. Includes the following elements:
– Periodic fee – is the fixed price of the service per one accounting period. Services of specialized types may have
some other components of price besides this one, namely, the price per unit of traffic or per connection time, etc.
– Charge method – is the order of charging off the user’s account. The possible values are:
* At the beginning of the period means that the charge-off is done at one instant on creation of the service
link;
* At the end of the period means that the charge-off is done at once immediately before the closing of the
accounting period (the one associated with the service link);
* Flow method means that the charge-off is done in portions during the whole length of the accounting period.
The number of portions is determined by the corresponding parameter of the accounting period, if it is set, or
by the core settings otherwise (the flow_discounts_per_period parameter). This parameter is set in the
tarrification settings (see Parameters on page 67)
– Charge policy. – is the default charge policy that will be used for service link creation for this service. For more
information on charge policy. For more information on Charge policies see: Basic system objects: Charge
policy on page 22And Administrator’s interface: Charge policies on page 46.
– Scheme ID – coefficient scheme applied to the service periodic fee. For more information on coefficient schemes
see Basic system objects: Coefficient scheme on page 23and Administrator’s interface: Coefficient
schemes on page 56


49
Tariffication 

– Contract type – comment that can be selected from a list of precreated comments. For more details see
Administrator’s interface: Contract types on page 57
If the flow method is selected, the charge-off is performed as follows. Based on the price of the service and the length
of the accounting period, the minimal one-time payment value is determined. Based on the number of charge-offs, the
minimal time between charge-offs is calculated. Once the service link is initialized, the corresponding accounting period
is divided into equal parts. At the end of each part, the total cost of the service to the moment and the total payments
for the service to the moment are determined, and if the difference between these two values exceeds the minimal
payment, then the sum rounded to the multiple of the minimal payment is charged off the user’s account.
If the number of charge-offs per week is not set in the accounting period properties, the period is divided into equal parts
anyway, but the number of parts is given by the flow_discounts_per_period system parameter (by default 64). At the
end of each part a business logic event is generated. The event handler runs through all periodic services linked to this
period and having flow method of charging. For every such service, the amount to be charged is determined, and if it
exceeds the discount_barrier parameter, the charge-off is made.
All these parameters are also relevant for services of other types, which however possess a number of extra
parameters specific to each type.
Parameters of the corresponding service link are described in Periodic service link on page 91.

IP traffic service
IP traffic service properties window contains the following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– Traffic aggregation interval – is similar in meaning to the global interface parameter called
traffic_aggregation_interval (see Settings available in the administrator’s interface on page 117), only limited
to this service alone.
– Limit of simultaneous sessions – is the limiting number of simultaneous sessions. It is only set when the
service is created and it can’t be changed later.
– Reset prepaid traffic – is the flag of resetting the prepaid traffic at the end of the accounting period. If set, the
unused prepaid traffic is cast to zero, otherwise it is transferred to the next period.
– Dynamic IP address allocation – is used to link this service to another one of hotspot or dialup type (also having
this flag set) in order to perform combined tariffication based together on connection time and traffic consumption.
One account may have only one IPtraffic service with this flag set.


50
Tariffication 

– Tariffication borders contains the tariffication borders, which are the traffic volume values defined for different traffic
classes separately and used to set variable traffic prices per megabyte depending on the amount consumed within
the accounting period. Each border specification consists of the following values:
– Traffic class (or a group of classes, see below);
– Traffic volume;
– Price.
The price linked to this border determines the cost of the traffic of this class from the current to the next border.
There is a default (hidden) border at traffic volume 0 having price 0.
– RADIUS parameters – (see Additional RADIUS attributes on page 71).
– Groups contains the interface of group tariffication. Group is a union of several traffic classes. The use of groups
alters the very logic of tariffication in a following way.
Each group is characterized by type, which may be either max or sum.
A group of type max is tariffed by the prevailing class, i. e. the price for the whole group is determined via
tariffication borders based on the amount of traffic for the class with maximum traffic. This means that when the
amount of traffic of any class reaches the tariffication border, the rest of the traffic will be tariffed with the new price.
A group of type sum is tariffed by the price determined according to the summary amount of traffic for all classes.
This means that when the sum of the amounts of traffic for all the group member traffic classes reaches the
tariffication border, they will be tariffed with the new price.

Groups must be created ahead of the tariffication borders. Once the custom borders are defined, the group
creation interface is disabled. Once the custom borders are defined, the group creation interface is disabled.

– Prepaid traffic. contains the list of prepaid traffic amounts for each of the traffic classes. The prepaid traffic is
expended first of all and tariffed by zero price. At the end of the accounting period the unused prepaid traffic is
transferred to the following period. The Accumulate no more than parameter, if set to a non-zero value, limits the
amount of unused traffic that may be transferred so, regardless of its origin. If the parameter is set to 0, accumulation
of prepaid traffic is not limited.

Prepaid traffic and group tariffication are mutually exclusive options, i.e. their simultaneous use is impossible.

Parameters of the corresponding service link are described in IP traffic service link on page 93.

Hotspot service
Hotspot service properties window contains the following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– Limit of simultaneous sessions – sets the maximum number of concurrent connections that may be
established with the same login.
– Dynamic IP address allocation – is used to link this service to another one of IP traffic type (also having this flag
set) in order to perform combined tariffication based together on connection time and traffic consumption. One
account may have only one hotspot or dialup service with this flag set.


51
Tariffication 

– Allowed networks – contains the list of allowed IP addresses from which the user is allowed to authorize on the
UTM5 web interface. Authorization requests from other addresses are denied.
– Price per hour – contains the list of connection time prices for various time ranges.
– RADIUS parameters – see Additional RADIUS attributes on page 71.
Parameters of the corresponding service link are described in Hotspot service link on page 95.

Dialup service
Dialup service properties window contains the following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– Pool name – is the name of the pool (see IP Pools on page 75) to issue the addresses from. These parameters
are cached by UTM5 RADIUS. If the pool is registered in UTM5, the first available IP address from it is issued.
Otherwise the pool name itself is passed instead.
– Maximum timeout – is the maximum session duration until forced break (in seconds).
– Limit of simultaneous sessions – sets the maximum number of concurrent connections that may be
established with the same login. These parameters are cached by UTM5 RADIUS.
– Login prefix – is the prefix to be prepended automatically to the user’s login on creation of a service link.
– Dynamic IP address allocation – is used to link this service to another one of IP traffic type (also having this flag
set) in order to perform combined tariffication based together on connection time and traffic consumption. One
account may have only one hotspot or dialup service with this flag set.
– Price per hour – contains the list of connection time prices for various time ranges. Must contain at least one entry.
Time is counted with precision to seconds.
– RADIUS parameters – see Additional RADIUS attributes on page 71.
Parameters of the corresponding service link are described in Dialup service link on page 95.


52
Tariffication 

Telephony service
Telephony service properties window contains the following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– Minimal invoice sum – is the minimum service cost for the customer.
– Free time – is the time threshold (say, 5 sec.) for free calls. Longer calls are charged for based on the full time
of the call.
– Starting period length – is the length of initial period having special rounding step.
– Starting period step – is the rounding step for the starting period.
– Next period step – is the rounding step for the rest of the call.
– Tariffication unit size – is the size of time unit to set the price for.
– Limit of simultaneous sessions – sets the maximum number of concurrent connections that may be
established with the same login.
– Discount free time – flag, when checked, makes the system consider the prepaid time (see ) in the cumulative
summary duration of calls on which the call price per minute may depend.
– Price editor. contains the list of call time prices defined separately for various time ranges and for various telephone
zones and/or directions.

To create a telephony service, at least one telephone zone or direction must exist in the system.

The prices may be updated all at once according to an arbitrary formula.

For example, to mutiply the prices by 1.1, select the rows in question, enter the formula x*1.1+ 0, and press
Enter. In order to add 10 to the price, select the rows in question, enter the formula x*1.0 + 10, and press Enter.
– Tariffication borders contains the tariffication borders, which are the values of total duration of calls per accounting
period defined separately for different telephone zones and/or directions and used to set variable call prices
depending on the summary duration of calls within the accounting period.

To set the tariffication borders for a particular telephone zone or direction, this zone or direction must be present
in the price editor (see above) of this telephony service.

– Prepaid values contains the amounts of prepaid telephone traffic allocated separately for different telephone zones
and/or directions.


53
Tariffication 

– Fixed cost contains the fixed cost of a call defined separately for different telephone zones and/or directions. This
cost is imposed on every call, regardless its duration, in addition to the variable part defined in Price editor and
Tariffication borders.
– RADIUS parameters (see Additional RADIUS attributes on page 71).
Parameters of the corresponding service link are described in Telephony service link on page 95.

IPTV service
IPTV service becomes available after purchasing IPTV integration module license. It’s properties window contains the
following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– IPTV system type is the type of the IPTV system that UTM5 is used with. – By default it is set to NetUP and
that way the service is configured to work with NetUP IPTV system. That makes available two other parameters
- Media content, which allows one to grand access to a certain media content and Media group which allows one
to grant access to a group of media contents. For more information on media content and media groups, see
NetUP IPTV Administrator’s guide. When this parameter is set to Other, the only available parameter is Custom
options.
– Custom options – is custom options that are passed to a corresponding UTM5 RFW event. It is an arbitrary text
field that may contain a string of data.
– Media content – is media content that the user will be granted access to when this service will be attached to her
account.
– Media group – is media group that the user will be granted access to when this service will be attached to her
account.
Parameters of the corresponding service link are described in IPTV service link on page 96.


54
Tariffication 

Video on demand service

Video on demand (VoD) service becomes available after purchasing IPTV integration module license. It’s properties
window contains the following pages:

– Main – (standard, Services on page 48).

– Service parameters – see Periodic service on page 49. In addition, contains the following parameters:
– IPTV system type is the type of the IPTV system that UTM5 is used with. – By default it is set to NetUP and
that way the service is configured to work with NetUP IPTV system. That makes available two other parameters
- Media content, which allows one to grand access to a certain media content and Media group which allows one
to grant access to a group of media contents. For more information on media content and media groups, see
NetUP IPTV Administrator’s guide. When this parameter is set to Other, the only available parameter is Custom
options.
– Custom options – is custom options that are passed to a corresponding UTM5 RFW event. It is an arbitrary text
field that may contain a string of data.
– Media content – is media content that the user will be granted access to when this service will be attached to her
account.
– Media group – is media group that the user will be granted access to when this service will be attached to her
account.
Parameters of the corresponding service link are described in Video on demand service link on page 97.

Service templates
The Service templates page contain the list of registered service templates (see Basic system objects: Service
templates on page 20) with the interface for creating, removing, or editing them. A service template can be removed
only if it is not used at the moment. Otherwise, in the first place it is necessary to remove all services derived from it.
Service templates serve solely as the parent entities for the services included in tariff plans. The properties of a service
template are essentially similar to those of a service of the same type (see Services on page 48), except for:
– Attach by default – means that the service will be linked to the customer as soon as the tariff link is created
– Allow multiple linking – allows one to link the same service to the same customer multiple times
The parameters of the services, created based on the templates may be edited when creating a tariff plan. Any changes
to the added service do not change the parent service (template) settings.

Time ranges
This page contains the list of registered time ranges (see Basic system objects: Time ranges on page 23). with the
interface for creating, removing, or editing them Range.


55
Tariffication 

A time range can be removed only if it is not used at the moment. Otherwise, in the first place it is necessary to remove
all entities (services, tariff plans, accounts, etc.) relying on it.
Below is the list of time range parameters and their meanings:
– ID – number (assigned automatically).
– Priority – is the order of precedence of time ranges in case they overlap (see below). The higher the number in the
Priority field, the higher priority the time range has.
– Name of the range.
– Range – is the set of time intervals that actually constitute the range.

The and buttons open the Time range window containing two tabs: Visual and Simple.

On the Visual tab a visual editor of time ranges is presented. Colored cells correspond to the hours included in the
range. To include or exclude a single cell, click on it once. With Shift key pressed the selection works in block mode,
i.e. encloses the whole block once its opposite angles are marked by two consecutive mouse clicks. With Ctrl key
pressed the selection works in intersection mode, i.e. spans onto cells coinciding by one coordinate with the cell being
selected, and by the other coordinate with those selected earlier.
The Simple tab presents text interface for setting time ranges. By pressing Add and Remove enter time ranges for
whatever days of week you need.

Visual interface is restricted to hourly precision, i.e. treats each hour as a whole; more accurate timing is possible
only within the text interface. Once the fractional hour borders get involved, the visual interface is rendered
view-only.

In the Days field you may enter individual days to be included in the range. These days are included as a whole, from
12:00 a.m. till 11:59 p.m. If the list of days and the table of hour ranges are used simultaneously, the time range consists
of their union.

If the two time ranges overlap, the ambiguous time is appropriated to the one with higher priority. In the case of
equal priority the outcome is platform-dependent and generally unreliable. Such collisions are to be avoided.

Coefficient schemes
This page contains the list of registered coefficient schemes (see Basic system objects: Coefficient scheme on
page 23). with the interface for creating, removing, or editing the schemes.


56
Tariffication 

A coefficient scheme may be deleted only if a service that uses this scheme hasn’t been used in any service links. If
a service is used in a service link, one has to delete the service link to be able to delete the coefficient scheme. Deleting
the service is not necessary. After deleting a coefficient scheme, it will be automatically removed from the service.
A coefficient scheme has the following parameters:
– ID – number (assigned automatically).
– Scheme Name.
– Comment.
– Scheme Creation date.
– Scheme Change date.

The and buttons open the Coefficient scheme window that allows one to add and
remove coefficients affecting the service price over the specified time period:

– Since – is the serial number of the accounting period from which the coefficient becomes active
– Till – is the serial number of the accounting period, after which the coefficient will be inactive

The serial number of an accounting period is set automatically. The order of the accounting periods numbers
is individual for each service link and starts from zero: 0 – is the serial number of the accounting period that was
set during the creation of the service link, 1 – is the serial number of the first full accounting period, 2 – the serial
number of the second full accounting period and so on, depending on the duration of the service link

– Coefficient – Is the multiplier that is applied to the service cost in the set period of time

The service cost is 100% over the periods that are not covered with coefficients

Contract types
This page shows the list of contract types. with the interface for creating, removing, or editing them.
Contract type is an additional comment to a service. A contract type may be added to any number of services. A
contract type may be added when creating or editing a service (see Services on page 48). A contract type must be
Added on the Contract type page in order to get to the available contract types list.
A contract type has the following parameters:
– ID – number (assigned automatically).
– Name.
– Creation date.
– Modification date.


57
Reference book 

The and buttons open the Contract type window:

After editing a contract type, its value will change in all the services that are using it. If a contract type is removed from
the system, it is also automatically removed from all the services.

Reference book

Payment methods
This page contains the list of payment methods (see Basic system objects: Payments on page 24) used to make
payments.
The predefined payment methods (those with ID<100) are not editable. User methods are automatically given
sequential IDs starting from 100. These methods are functionally equivalent to the predefined Cash payment method.
User methods are editable, but can not be removed.

Currency
This page contains the list of registered Currencies (see Basic system objects: Currencies on page 24). with the
interface for creating, removing, or editing them Currencies. The and buttons open the
Currency details window.
Currency is characterized by the following parameters:
– ID – is the digital currency code according to ISO 4217.
– Abbreviation – is the three-letter currency code according to ISO4217.
– Name – is the full name of the currency.
– Percent – is an arbitrary correction to the exchange rate which is applied upon
its online update.
– Exchange rate – is the exchange rate against the internal system currency.
The Online update button evokes the online update of the currency exchange
rate. Russian rouble exchange rate is always 1. The Online update functionality
is only available if the system_currency (see Parameters on page 67) is set to
Russian ruble (ISO code 810), which is the default setting.

This shall not be confused with the standard button next to the list of currencies, which refreshes
only the list of currencies, but not their rates.

By default 1 russian rouble equals 1 system unit, meaning that all calculations are performed in roubles.
– Currency rate history – contains the history of former exchange rates in the system. The first line of the table
contains the current currency exchange rate.

IP zones
List of IP zones is intended for operations with large multi-segment and distributed networks, and contains data on
various network segments, including network, mask, and gateway. An IP zone may consist of one or several segments.


58
Reports 

IP zones can not be removed.

Buildings
List of connected buildings is intended for convenient operations with networks that span several buildings. The record
on house contains its address and the ID of its IP zone. When a user is connected to a house (see : Contacts on
page 35), the IP addresses for the user are issued from the IP zone associated with the house, see IP traffic service
link on page 93.
Buildings can not be removed.
Users may be connected to houses. An example is given in Linking a user to a house on page 108.

Banks
List of banks serves to quickly fill the bank data in the forms. A bank ID is linked to the following data: BIC, name,
address and correspondent account. Users may be connected to banks (see : Additional parameters on page 35).
An example is given in Linking a user to a bank on page 108.

Reports
UTM5 supports a variety of reports (see the list below). Reports can be generated either for a certain user or for all users
at once. Generated reports can be saved as an external file of XML or CSV format.
It is possible to set any time interval for a report to be created. The interval is either entered manually or set to one of
the accounting periods.

When a report for all users is composed, it may be limited to some group of users by selecting the group from the
drop-down list.
When a report for one user is composed, it may be limited to one of the user’s accounts.
The Filter roll-up pane may be used for additional filtering of the report data. The exact list of available filtering
parameters depends on the report type . An arbitrary set of conditions may be specified and logically combined as either
All conditions or Any condition.

If the number of entries in the report exceeds 9999, a warning message shows up during its generation. In this case it
may be worthwhile to interrupt the operation and generate the report again with narrower sampling, to avoid memory
overflow.
Any report contains the summary line that sums up the values across each column.

General report
General report (turnover balance sheet) summarizes all flow of funds on the user's personal accounts during the given
time span.
The report includes the following data:


59
Reports 

– Account ID;
– Initial balance;
– One-time service charges;
– Periodic service charges;
– IP traffic service charges;
– Hotspot service charges;
– Dial-up access service charges;
– Telephony service charges;
– Tax amount;
– Total sum adjusted for taxation;
– Total sum of charges;
– Closing balance.
The general report does not contain the charge-offs caused by the nullification of one’s balance at the end of accounting
period (if this option is employed), those caused by the expiration of expiring payments, and the credit payments.
If the selected time span contains no flow of funds, then all columns, including the incoming and closing balance, will
read 0.

Traffic report
Traffic report summarizes the amount of transferred IP traffic for each personal account and traffic class during the
given time span.
Traffic report includes the following data:
– Account ID;
– Login;
– Number of bytes in a kilobyte;
– Traffic class;
– Amount of traffic transferred (in megabytes);
– Price per unit of transferred traffic (cost of 1 MB);
– Sum charged off the user’s personal account.
The data may be grouped by IP addresses, by hours, by days, by months, or by groups of users.

Report on services
This report summarizes information on charge-offs from the user account made during the given time span for the
provided services. The report includes the following data:
– Account ID;
– Date of charge;
– Accounting period;
– Service type;


60
Reports 

– Service name;
– Amount of service provided.
Besides the total summary line, the lower part of the report contains separate sub-totals on various types of services.

Telephony report
Report on telephony sessions is based on RADIUS server statistics and summarizes data on telephony sessions
(calls). The report includes the following data:
– Session ID;
– Account ID;
– Receive date;
– Start date; End date;
– Calling station ID;
– Called station ID;
– NAS port;
– Access server (NAS) session ID;
– Login;
– NAS IP address;
– Session status;
– Incoming traffic amount;
– Outgoing traffic amount;
– Telephone zone;
– Telephone direction;
– Session duration;
– Rounded duration of the call (calculated based on the rounding step as set in the properties of the telephony service);
– Incoming trunk; Outgoing trunk;
– PBX ID;
– Cost per unit time;
– Total cost;
– Disconnect reason.
A call spanning across the border between time periods having different prices per minute is nominally split in two and
represented in the report as two calls with the same session ID but with different prices per minute.
A call that has not been tariffed yet is represented in the report as a call with zero price.
Besides the total summary line, the lower part of the telephony report contains sub-totals on individual telephone
directions.

Telephony directions report

This report contains data on phone calls aggregated by telephone directions. For each direction it includes:
– Parent telephone zone ID;
– Direction ID;
– Zone name;
– Direction name;


61
Reports 

– Total calls duration;

– Total calls cost;
– Number of calls;
– Number of calls with nonzero duration.

Sessions report
Report on modem sessions and VPN sessions is based on RADIUS server statistics and summarizes data on dialup
access sessions. The report includes the following data:
– Session ID;
– Account ID;
– Start date;
– End date;
– Calling station ID;
– Called station ID;
– IP address issued by NAS;
– NAS port;
– Access server (NAS) session ID;
– Login;
– NAS IP address;
– Session status;
– Incoming traffic amount (bytes);
– Outgoing traffic amount (bytes);
– Incoming traffic amount (gigabytes);
– Outgoing traffic amount (gigabytes);
– Session duration;
– Disconnect reason.
– Total cost;
Sessions registered on the RADIUS server (i.e. probably currently active) are highlighted in green.

Report on blockings
This report summarizes information concerning all blockings (see Accounts on page 16) set within the given time
span. The following data are available in the report:
– Account ID;
– Blocking start date;
– Blocking expiry date;
– Blocked item;
– Blocking type;
– Blocking comment.


62
Reports 

Report on payments
This report provides information about payments made by a certain user during the given time span. The following data
are available in the report:
– Account ID;
– Actual payment date;
– Date of payment processing by the system;
– Sum of payment in system currency;
– Sum of payment in payment currency;
– Currency of payment;
– Payment method;
– Payer;
– Payment comment.
For the Credit payments, the payment status is automatically filled into the Comment field:
– Credit opened till: <date> – is the status before the expiration date;
– Credit closed successfully – is the status after expiration if the account balance is positive;
– Credit overdue – is the status after expiration if the account balance is negative.
Besides the total summary line, the lower part of the report contains sub-totals on various methods of payment.
The context menu of the payments report contains the following extra items:
– Print receipt – for the given payment;
– Roll back – the given payment (not applicable to expiring payments).

Report on expiring payments

This report summarizes the information on expiring payments during the given time span, including the following: The
following data are available in the report:
– Account ID;
– Login;
– First payment date;
– Last payment date;
– Payment expiration date;
– Amount;
– Already charged off.
Expired payments are not included in the report.

Other charges
This report contains information about the charge-offs other than service charges, including:
– Expiration of expiring payments;
– Payment rollback;
– Resetting of user’s account to zero at the end of period.
In addition, the report contains rebates for the services not used because of blocking, if some of the user’s service links
have their recalculation options set correspondingly.


63
Reports 

Besides the total summary line, the lower part of the report contains sub-totals on various transaction reasons.

Internal transfer
This report provides information about the internal transfers of funds, i. e. the transfers between different accounts of
one user, made either via web interface or via utm5_tray application.

Report on invoices
This page allows one to generate the following report types:
– Invoice;
– VAT invoice;
– Acceptance report;
– Detail invoice.
Each report type is generated in a separate tab.

This report summarizes the information on invoices issued during the given time span, including the following:
– Internal number;
– Alternative number;
– External number;
– Account ID;
– Full name;
– Time;
– Paid (invoice status);
– Sum;
– Creation date;
– Modification date;
– Status
– Is mailed.
The report for a single user contains an additional button New invoice that may be used to generate a New invoice
with arbitrary positions. Each position is characterized by:
– Name
– Quantity;
– Cost per unit;
– Total cost (calculated automatically).


64
Reports 

The context menu of the invoices report contains the following extra items:

– Pay opens the New payment window (see page 88). Payment sum set to the sum of the selected invoice. After
commiting a payment, the invoice is marked as Paid. This oprion is only avaialbe on the Invoice tab.
– Edit – opens the selected invoice in ODT format for editing.
– View – opens the selected invoice in PDF.
– Rebuild – generates the invoice again. E.g. this might be useful when after generating an invoice, the administrator
decides to edit one of the document templates.
– Save as ODT allows one to save the invoice in ODT format.
– Save as PDF allows one to save the invoice as PDF.
– Send by e-mail sends the selected invoice(s) to the e-mail set in the user’s properties.
– Correction of invoice positions allows one to arbitrarily edit invoice positions. Correction is available for periodic
fees positions. Any change to invoice positions will affect personal account’s balance in order to preserve the report’s
integrity. E.g. when reducing position cost by $5, account’s balance will increase by $5; This oprion is only avaialbe
on the Invoice tab. 

All changes made via correction of invoice positions appear in the User change log. The corresponding Invoice entry
will have a Invoice position correction record in it’s Action column, the ID of the corrected entry in the DB, the amount
of correction and new account balance in the Comment column.
– Delete invoice allows one to delete an invoice. This oprion is only avaialbe on the Invoice tab.

User change log

This report lists the changes made to user properties and to some other system objects (services, tariff plans, etc.)
during the given time span, including the following information: The following data are available in the report:
– User ID (0 if the change is not related to a user).
– Login (empty if the change is not related to a user).
– Who – is the login of the system user responsible for the change.
– Time; – is the date and time when the change was made.


65
Reports 

– What – is the short description of the change.

– Comment.
– Action – Is the record type. It contains values that can be used to filter this table.
Changes of some particular kinds may or may not get included in the report, depending on the way they were made
(say, automatically or manually).
This report has a quick filter that allows to filter the list of entries. Select an action type to reduce the number of visible
entries.

Detailed traffic report

This report includes the following detailed information concerning the transferred traffic:
– Date;
– Service link ID;
– Account ID;
– Traffic class;
– IP address and source port;
– IP address and destination port;
– Number of transferred packets;
– Number of transferred bytes;
– TCP flags;
– Protocol;
– TOS.
Detailed statistics over a long time interval typically constitutes huge amounts of data, so the formation of detailed traffic
report may take quite a while. In such cases we recommend to use ordinary Traffic reportinstead, or query the
database directly using get_nf_direct. If creation of a report is taking longer than expected, it may be interrupted
(see Tray icon on page 97).

Graphic report
Graphic report is used for visual data representation. The available data types are listed in the Service type dropdown
list:
– IP traffic – represents the traffic consumption by all users, grouped by traffic classes;
– Dialup – represents the number of dialup sessions per hour;
– Telephony – represents the number of phone calls per hour.

Custom charges report

This report provides information on the charges performed by third-party systems via integration modules (see
External charges on page 14), and includes the following fields: There are the following columns in the report:
– Account ID;
– Login;
– Date;
– Mark (a unique ID of the transaction);
– Amount;
– Amount with tax;


66
Settings 

– Service;
– Service ID;
– Revoked (a flag that shows whether the charge has been revoked).

DHCP lease
This report provides information on the IP address lease history (IP addresses provided by the UTM5 DHCP module).
There are the following columns in the report:
– ID
– Login;
– IP
– MAC
– Updated (date and time of lease update)
– Expired (time and date of lease expiration)

Settings

Parameters
This page contains the system core parameters that are set via Administrator’s Interface. These parameters are divided
into the following groups:
– Tarrification settings
– Card user settings
– Notification settings
– SMTP protocol settings
– Invoice document settings
– Other settings
– RADIUS protocol settings
– Default settings
Select a settings group and double click it or press . This will open a popup window with a list of editable
parameters:


67
Settings 

If a parameter is underlined hover over it to read a help message:

The Traffic aggregation timeout and Minimum traffic charge threshold parameters define the rate at which the
customer's personal account is being charged.

These parameters are considered simultaneously. Customer’s personal account is charged when either
condition is satisfied: The aggregation timeout is exceeded or the amount of traffic has reached the threshold.

The lower these parameters, the faster will grow the tables that store charges statistics. Those tables are the
largest in the database and may require table archiving in order to reduce the DB load (see Archiving of tables
on page 201).

Invoice document settings

Invoice document settings window contains two parameters that determine invoice position aggregation rules. The said
are Rules for invoice generating and Rules for prepaid invoice generating.
An aggregation rule consists of comma-separated field names. To have service-related positions included in a single
invoice, the field values must be equal for these services.
E.g.:
The rule is company.id, which means that entries that share the same service provider will get into the same invoice.
Let’s suppose we have three services: (1) IP traffic and (2) Hotspot from one service provider (sharing the same
company.id=1) and (3) telephony service from another service provider (company.id=2). Services (1) and (2) must
generate two entries each - A, B and C, D respectively. Service (3) also generates two invoice entries - E, F. The result
will be two invoices: The first one will contain entries A, B, C, and D, the second one – will contain entries E and F.
The following field names are allowed for setting the rule:
– tariff.link_id – is a tariff link ID
– tariff.id – is a tariff plan ID
– tariff.name – is a tariff plan name
– service.link_id – is a service link ID
– service.type – is a service type
– service.id – Is a service ID
– service.name – is the name of a service
– company.id – is the service provider ID
– company.name – is the name of the service provider
Use colon to separate rules for services that are included in a tariff plan from ones that are not (common services). In
this case, if a user have a tariff plan and a common service connected, two invoices will be generated. If a user have
only a tariff plan connected, a single invoice will be generated.
The following preset rules could be used as well:
– default – predetermined field name set (see description below);
– single – all services will be included in a single invoice;
– separate – two invoices will be generated: one is for tariff plan services and the other is for common services.


68
Settings 

The default rule is equivalent to the following:

tariff.link_id,company.id:service.link

This means that two invoices will be generated. One will include all positions for the services that are associated with
the same tariff plan and the same company. The other will include the positions for each common service.
The single rule is equivalent to empty parameter value field:

No field names are set, thus all positions will be included in a single invoice.
The separate rule is equivalent to setting colon in the parameter value field:

No field names are set, but the colon determines that all common services will be calculated separately. Hence, if a
user have both tariff plan services and common services connected, then two invoices will be generated.

Additional parameters
provides the functionality of custom user parameters. Once created, those parameters may be assigned, viewed, and
edited via the administrator’s interface along with the rest of user’s properties, as well as used in the document
templates. This page contains the interface for creation, modification, and removal of additional users’ parameters.
Parameters’ values for the particular user are set on the user properties page (see : Additional parameters on
page 35). To make a parameter appear there, the Visible option has to be checked upon its creation.

Firewalls
This page contains the list of firewalls registered in the system (see UTM5 RFW on page 137) together with the
interface for creating, removing, or editing them. Working firewalls are highlighted in green.
Each firewall has the following parameters:
– ID – is assigned automatically;
– Type – may be one of the following:
– Local – firewall is used;
– Remote Cisco – firewall controlled via rsh is used.
Firewall type must conform to the firewall_type parameter of the config
file associated with this firewall.
– Name – is the parameter by which the core identifies various rfw. Name must
conform to the rfw_name parameter of the config file associated with this
firewall.
– IP – address of the NetFlow supplier stated in the properties of IP traffic service link. I.e. a NetFlow provider should
be registered as a firewall.
– Login – for rsh authorization. Only for Remote Cisco firewall type. netup is always used as the local login.
– Comments – are optional.


69
Settings 

Firewall rules
This page contains the list of firewall rules together with the interface for creating, removing, or editing them.

The and buttons open the Firewall rule window containing the firewall properties.

The meanings of particular parameters, as well as the general usage of firewall rules, are described in UTM5 RFW on
page 137.

NAS list
The NAS list page contains the list of registered network access servers.

Each NAS is characterized by the following parameters:

– ID – Is the NAS ID.


70
Settings 

– NAS IP – is the NAS IP address (see IP addresses on page 25for the formatting details.)
– Auth Secret – is the password used to process authorization requests from NAS and send responses. Must
coincide with the common secret word set in the NAS properties for this type of requests.
– Acc Secret – is the password used to process accounting
requests from NAS and send responses. Must coincide with the
common secret word set in the NAS properties for this type of
requests.
– DAC secret – is the password used in sending extended
messages (RFC 5176). We recommend using strong passwords.
– DAE server port – is the port on NAS appointed to receive
extended messages.
– ISG profile – is an ISG profile that will be used to treat requests
coming from this particular NAS (see ISG profiles on page 73).
– Send disconnect request – flag authorizes the use of
Disconnect-request packets on this NAS (for more information see
UTM5 RADIUS: DM and CoA requests on page 121).
– Send CoA request – flag authorizes the use of
Change-of-Authorization packets on this NAS (for more information see UTM5 Dynashape: Workflow description
on page 148).
– Set RADIUS parameters – Opens the RADIUS parameters window (see below Additional RADIUS attributes)

Setting RADIUS attributes is only possible after registering a NAS. One needs first to create a NAS, then open
it for editing. Then the RADIUS attributes will be available for adding.

– Parameters list – opens the NAS settings window. It allows one to use custom RADIUS settings for the selected
NAS.

Additional RADIUS attributes

A list of additional RADIUS attributes for Access-Accept to the given NAS may be set using the Set RADIUS parameters
button included in NAS properties, service properties, and service link properties.

UTM5 5-3.004 now supports tagged RADIUS attributes.

A RADIUS attribute has the following parameters:

– Vendor – is vendor ID
– Attribute – is attribute ID
– Value – of the attribute.
– Type – must be either Number, String, IP address, or Binary.
– Use in – is the request type to which this attribute should be added.
– Usage settings – are the settings that allow one to do the following
operations when adding additional attributes to a RADIUS request:
– Replace Attribute – replaces the value of a previously created attribute
with the same ID with the value of the current attribute.
– Remove Attribute – removes previously created attribute that has the
same ID.
– Enable scripting – allows one to use scripting to solve complicated
tasks. E,g, if one needs to create a vendor specific attribute and use a
standard attribute value. To do so, fill the Value field with vendor ID and
attribute ID, in curly braces, separated by comas. E.g. {9, 44}


71
Settings 

– Expire settings – allows one to set an expire date for this rule. So that these additional attributes will not be added
to the RADIUS requests after the expire date.
The additional RADIUS attributes may set some connection parameters (bandwidth limitation, protocol, addresses,
etc.) for each service, for a service link, or for a NAS. The access server must be able to support those attributes.
RADIUS attributes are described in RFC 2865 and RFC 2866.

RADIUS accounts
This page contains the list of RADIUS accounts.

A RADIUS account allows one to log in on a RADIUS server and receive authorization parameters as a set of attributes
that are included in an Access-Accept response type.

Press to add a new RADIUS account

A RADIUS account has the following set of parameters:
– ID – is assigned automatically
– Name – is a login name for RADIUS server authorization. It
must be unique for the whole UTM5 system
– Include NAS attributes flag – makes RADIUS server include
the attributes, specified in NAS settings to its response (see
NAS list on page 70)
Then comes a table of attributes that need to be included in the
RADIUS server response, when one logs in with this account:

– press to add an attribute

– press to edit selected attribute

– press to delete selected attribute

Press on the RADIUS accounts page to edit parameters of the selected account.

Press to delete selected account.

Press to refresh the list of accounts.


72
Settings 

ISG profiles
This page contains the list of ISG profiles.

ISG profiles are used for configuring the interaction between RADIUS server and intelligent gateway IPoE (i.e. Cisco
ISG). These profiles are used as a parameter for registered NASs.

Press to add a new ISG profile. An ISG

profile has the following set of parameters.
– ID – is assigned automatically
– Name – is an arbitrary information field
Next comes the Authorization parameters group. These
parameters determine how to treat authorization
requests:
– Login type – is the type of data that comes in the
User-Name attribute of the authorization request. May
be MAC, IP or Login in IP group
– Password type – determines if the password should
be compared to the password from the IP group
properties or with a static password (in that case a
Password field will appear)
– Authorization timeout – is time in seconds to wait
for the first packet with an Accounting-Start code. If
such a packet doesn’t come before timeout, RADIUS
server finishes the session
– Unlocked account code – allows one to choose a
response code for users whose personal account is
not blocked, requesting authorization. The response
might be Access-Accept or Access-Reject
– Blocked account code – the same as above, but for
users whose personal account is blocked
– Assign address flag – determines if the Framed-IP-Address attribute should be added to the authorization
response. The attribute’s value depends on the login type - MAC or IP. If the authorization type is IP,
Framed-IP-address attribute will contain the same IP address that was used for authorization. If the authorization
type is MAC, then an IP address determined by the IP group properties will be used (an address from a RADIUS
pool, set in the RADIUS options tab, or an address from the range, specified in the Static IP tab. For more
information see IP groups on page 93). If the authorization type is Login in IP group, then IP group settings are used
and this flag doesn’t determine whether the Framed-IP-Address attribute will be added or not.
Next comes the Attributes group of parameters, which is a list of additional RADIUS parameters which are added to
the authorization response.


73
Settings 

– press to add an attribute

The following parameters are set for a RADIUS attribute:
– Vendor – is vendor ID
– Attribute – is attribute ID
– Value – of the attribute.
– Type – must be either Number, String, IP address, or
Binary.
– Settings – allow one to specify the case when to add
this attribute. The attribute may be added depending on
the service or on account state (e.g. only when the
account is blocked)
– Usage settings – are the settings that allow one to do
the following operations when adding additional
attributes to a RADIUS request:
– Replace Attribute – replaces the value of a previously created attribute with the same ID with the value of the
current attribute.
– Remove Attribute – removes previously created attribute that has the same ID.
– Enable scripting – allows one to use scripting to solve complicated tasks. E,g, if one needs to create a vendor
specific attribute and use a standard attribute value. To do so, fill the Value field with vendor ID and attribute ID,
in curly braces, separated by comas. E.g. {9, 44}
– Expire settings – allows one to set an expire date for this rule. So that these additional attributes will not be added
to the RADIUS requests after the expire date.

– press to edit selected attribute

– press to delete selected attribute

Next comes the CoA group of parameters. These parameters determine if CoA requests are applicable and what
RADIUS attributes they should contain:
– Enabled flag – determines if CoA requests should be used

– press to add an attribute

Settings of an attribute added to a CoA request are similar to settings of an attribute that is added to a response to an
authorization request. They allow one to add an attribute depending on the event that caused this CoA request -
blocking/unblocking personal account or deleting the service link

– press to edit selected attribute

– press to delete selected attribute

When on ISG profile page, select one of the profiles and press to edit it.

Press to delete selected profile.

Press to refresh the list of profiles.

Companies
This page contains legal and financial data on the company’s legal entities to use in document templates.


74
Settings 

Telephony operators
This page contains the list of telephony operators. These must be stored by UTM5 in order to track mutual settlement
charges for the passage of another’s telephone traffic. When a Telephony operator is created or edited, the following
multi-page window shows up:

– Details – includes the properties of the legal entity identified with this operator, and also the balance of settlement
charges.
– Service – includes the parameters of the special telephony service intended solely to account for settlement
charges with this operator. This service does not show up in the list of services, can not be attached to ordinary
users, has no name, no prepaid traffic units, and no linked RADIUS attributes. Tariffication borders for this service
are not cumulative, i.e. the service usage amounts on which the price depends refer to one single call. In all other
respects it is just like usual telephony service (see Telephony service on page 53).
– Reports – (available only when editing an existing operator) includes the reports on payments and charges for this
operator.

IP Pools
This page contains the list of pools of IP addresses to be issued to dialup users.

При наличии нескольких If several IP pools share the same name then the usage thereof is controlled by the
parameter named_pool_shuffle (see UTM5 RADIUS: named_pool_shuffle on page 130). In earlier versions
of UTM (prior to 5.2.1-009-update2) the systems’s behavior in this case was unpredictable.


75
Settings 

Document profiles
This page contains a list of document profiles.

A profile of documents is a set of templates with one template for each document type:

These profiles are used for generating documents like contract or an invoice.
The Document profiles page gives access to the following actions:

– press to add a new profile of documents

– press to edit selected profile

– Press to delete selected profile.

– press to refresh the list of profiles

The first profile (default) can not be deleted. It is set as a default profile for all users. One can assign another
profile to a user in User’s properties (User > Other)

Replacements in documents
This page contains the list of replacements that can be used in document templates.

– press to add a new replacement

– select one of existing replacements and press to replace its value


76
Settings 

– press to delete a replacement

– press to refresh the list of replacements

Dynamic shaping
This page displays the dynamic shaping parameters for those services which are enabled with it, together with the
interface for enabling or disabling shaping and setting its parameters. Shaping is applicable solely to the IP traffic
services. One can add shaping, cancel itm or edit it's parameters.

The button disables shaping for the selected service.

The and buttons open the Dynamic shaping window containing the following interface
elements:

– Service – is the drop-down list for selecting the service to apply shaping to. Disabled during editing (may be set only
once).
– Apply to VPN IP, Apply to non-VPN IP – are the flags controlling the application of shaping to different types of IP
addresses. Disabled during editing (may be set only once).
– On the tabs Incoming and Outgoing:


77
Settings 

– Using the buttons Add time range and Remove time range select the time range to apply shaping.

Usage of the overlapping time ranges is inadmissible here, as well as in other circumstances.

– Using the buttons Add border and Remove border set the border values of traffic amount (in bytes) for shaping.
The units of K (kilobytes), M (megabytes), or G (gigabytes) may be used; if no units are given, the number is
interpreted as a value in bytes. It may be worthwhile to set the lower border to zero, so as to establish bandwidth
limitations for any amount of traffic starting from zero.

– For each border and for each time range set the bandwidth limitation. It will be valid during the given time range
if the amount of traffic is above the given border (and still below the next one, if any).
– In the Traffic classes group enter the desired traffic classes to apply shaping to, using the drop-down list and the
buttons Add traffic class and Remove.
– Turbo mode tab is optionally used to set up the turbo mode, which is a brief temporary enhancement of Internet
access bandwidth. Its parameters include: bandwidth limitation for incoming and outgoing channels separately (or
no limitation whatsoever, if such an option is selected), duration, and the name of a one-time service used as a
payment for engaging turbo mode. Customers may switch turbo mode on via web interface at their own discretion.

If the turbo mode settings include the Traffic amount and the incoming and outgoing traffic limits are set, the
turbo mode will be switched off only when both limits are reached.

– The RADIUS parameters tab contains the parameters that wiil be sent to the RADIUS server: Vendor ID,
Parameter ID, and the string from the Value field. The command may include variables selected from the drop-down
list. On execution the variables are substituted with their values. See UTM5 Dynashape: RADIUS parameters on
page 149for the list of variables.

Emergency calls
This page contains the list of telephone zones and/or directions which are available for a call even when the user’s
account is blocked.


78
Settings 

Archive DB
This page contains an interface for automatic DB archiving

Press to archive DB tables.

For each archive the following fields are available:
– ID – is the arhive ID;
– Start time – is the first entry creation time;
– End time – is the last entry creation time;
– Status – is the archive status (OK, Verifying, Unable to verify).

Table archiving may be performed no more than once in 28 days.

In order for the archived data to be used in reports, the archived tables structure must comply with the core
requirements. Otherwise these data will be ignored. Press to verify the archived tables structure. When
the verification is finished, the Status column will display verification results (OK if an archive complies with the core
requirements and Need repair Press to repair the archived tables structure. In case of success, the
status will change from Need repair to OK. Otherwise the status will change to Unable to repair. Such tables can only
be repaired manually.

NetFlow providers
This page contains the list of NetFlow providers registered in the system.


79
Settings 

Each entry describes a NetFlow provider and has the following parameters:

– ID – internal ID that is assigned automatically

– Traffic collector – is the traffic collector responsible for processing network usage statistics coming from this
provider.
– Name – is the name of the NetFlow provider (must be unique).
– IP – is the IP address of the NetFlow provider.
– Comments – is an arbitrary comment.

Traffic collectors
This page contains the list of available traffic collectors registered in the system.

Each entry describes a traffic collector and has the following parameters:
– ID – internal ID that is assigned automatically
– Name – is the traffic collector name

This name must be the same with the value of the tc_name
parameter in the traffic collector's configuration file

– Comments – is an arbitrary comment

– Uptime – is the time since the start of the collector
– Netflow records – is the number of processed NetFlow records
– Netflow error records – is the number of non NetFlow records
The system collector is marked with turquoise background. It is present by default. Additional traffic collectors are
marked with green if they are started and have successfully connected to the UTM5 core. If a traffic collector hasn’t
started, or didn’t connect to the core for any reason, it is marked with red.
In order to set up a traffic collector:
– select one from the list


80
Interfaces 

– press and then press in the popup window to open traffic collector settings:

Interfaces
This section covers the settings affecting user’s and cashier’s interfaces. Tray settings (page 81)contains settings
related to utm5_tray application (see utm5_tray utility on page 173). Parallel functionality of the web interface may
be set up by editing the XML templates in the root directory of the interface.
The pages Tariff switch, Voluntary suspension, Promised payments, and Internal transfer (page 84)describe
each a particular facility defined by a set of parameters. An arbitrary amount of separate sets may be created. Each
set has its own priority and refers to certain group of users. If there are several sets defined for this group (or the user
belongs to multiple groups), only one set is applied, namely the one with the highest priority. When this set is disabled,
so is this facility for this user, despite possible presence of other sets, if even for the same group.
Priority of sets may be edited by the buttons Up and Down. There is one special set associated with the group All which
is present by default, can not be removed, and has fixed priority of 0 (i. e. below others).

Tray settings
This page controls the settings related to the client tray application (see utm5_tray utility on page 173).

The Update info group of parameters controls the automatic update settings:
– Enable update – switches on automatic update.
– New version build (number) – is the build number of new version of the user application. On startup it is compared
to the current version number, and once the current version is found to be outdated, it is updated.


81
Interfaces 

– URL – is the network address to download the new version from.

The Select tabs... group of parameters controls users’ access to particular interface pages (see utm5_tray utility:
Interface pages on page 174).
The Select available reports group of parameters controls users’ access to particular kinds of reports on the Reports
page (see utm5_tray utility: Reports on page 174).

Cashier interface
This page controls the settings of UTM5 cashier interface (see Cashier module on page 170).

Settings related to the payment page include:

– Show tab – checks whether or not include this page in the cashier’s interface.
– Search by – lists the parameters to allow searching by.
– Attributes to show – lists the parameters to show in the search results.
– Quantity; – is the number of users to show in the search results.
– Show comment – shows the comment field in the cashier’s interface.
– Currency – is the list of available currencies.
Settings related to the report page include:
– Show tab – checks whether or not include this page in the cashier’s interface.
– Attributes to show – lists the payment parameters to show in the report.

Tariff switch
This page contains the list of sets of parameters for switching tariff plans. The applicability of sets to a particular user
is determined based on group affiliation and priorities (see above).


82
Interfaces 

The and buttons open the properties window containing the following elements:

– ID – of the set.
– Group – of users to which this set is applicable.
– Activated – is the flag that enables the set.
– Instant change – is the flag that allows the plan to be switched instantly. Otherwise the plan will be switched at the
end of the accounting period.
– Changes per period – is the maximum allowed number of plan switches during one accounting period.
– Available tariffs – is the list of tariff plans eligible for the switch. The list is controlled by the buttons Add, Edit, and
Remove.

Each item in the list has the following properties:

– Tariff – is a tariff plan name
– Min balance – is the minimum value of the user’s balance required to switch plans;
– Service – is a one-time service used to collect fee for the plan switch;
– Free if balance over – is the minimum balance value required to switch plans for free.

Voluntary suspension
This page contains the list of sets of parameters for voluntary suspension. The applicability of sets to a particular user
is determined based on group affiliation and priorities (see above).

After suspension is activated, recurring fee is recalculated according to the periodic service link parameters (see
Periodic service link on page 91)

The and buttons open the properties window containing the following elements:


83
Interfaces 

– ID – of the set.
– Group – of users to which this set is applicable.
– Min duration of the suspension;
– Max duration of the suspension;
– Interval between uses of this facility;
– Min balance – is the minimum value of the user’s
balance required to use suspension;

Check the consider checkbox to the right of the

parameter value if the parameter should be
considered by the system If the checkbox is not
checked, the parameter will be ignored

– Service – is a one-time service used to collect fee for the suspension.

– Free if balance over – is the minimum balance value required to suspend for free.
– Enable self-unlock – is a flag enabling the user to lift the suspension prematurely.
– Activated – is the flag that enables the set.
After removal of a voluntary suspension, the account remains in the Internet: Off state untill the next payment, or till
the end of the month, or until turned on by the user, whichever happens sooner. The users may turn it on using the
utm5_tray application (see utm5_tray utility: Main on page 174) or via the web interface (see Web interface:
Accounts on page 178).

Promised payments
This page contains the list of sets of parameters for making promised payments. The applicability of sets to a particular
user is determined based on group affiliation and priorities (see above).

The and buttons open the properties window containing the following elements:
– ID – of the set.
– Group – of users to which this set is applicable.
– Max payment – that can be made.
– til positive balance flag – automatically sets the payment amount to minimum possible to turn the balance
positive;
– Max duration – is a promised payment expiration period;
– Interval between uses – of this facility
– Min balance – is the minimum value of the user’s balance required to make promised payments. If the Consider
flag is not set, the check is not performed;
– Service – is a one-time service used to collect fee for the promised payments.
– Free if balance over – is the minimum balance value required to make promised payments for free. If the Consider
flag is not set, the check is not performed;
– Activated – is the flag that enables the set.

Internal transfer
This page contains the list of sets of parameters for making internal transfers. The applicability of sets to a particular
user is determined based on group affiliation and priorities (see above).

The and buttons open the properties window containing the following elements:


84
Additional Features 

– ID – of the set.
– Group – of users to which this set is applicable.
– Activated – is the flag that enables the set.

Additional Features
– Statistics – summarizes info on uptime and the number of NetFlow records in the system.
– LibURFA Plugins – displays the list of plugins and their version numbers.
– Symbols – displays the list of URFA functions.
– Connections – displays the list of open connections.
– Hotspot sessions – displays the list of Hotspot sessions opened via the web interface (but not the RADIUS hotspot
sessions).
– RADIUS sessions – displays the list of active sessions on RADIUS server.
– RADIUS attributes – displays the list of custom RADIUS attributes. These may be attached to particular users,
network access servers, services of IP traffic, dialup, and telephony, and also to corresponding service links.
– Change password – contains the interface for changing the administrator password. The Change button turns
active only if New password and Confirm new password coincide.

Inventory
This group contains pages that allow one to tweak the entities, used by UTM5 DHCP module (see DHCP on page 184)

Switch types
This page contains the list of available switch types.

Press to add a new switch type. It has

the following parameters:
– Name – is the name for this switch type
– Supported volumes – is the number of available
ports for this switch type (may be several values,
comma separated, e.g. for different switch models)
– DHCP option 82 parameters – is a description of
the option 82 parameters used to attach an IP
address to a switch, acting as a DHCP Relay or to
a switch port which the DHCP request came from.
DHCP option 82 carries a switch ID (Remote ID),
port number and VLAN ID. Each parameter has:
– Not active – (remove this flag to use a parameter)
– Type – is a parameter type (string or binary) Port and VLAN ID parameters consider bytes order when using
Binary type. One can select between Binary (BE) - big endian or Binary (LE) - little endian
– Disposition – is a suboption of the option 82 to which the offset is applied. Suboption code is considered to be
the start of the suboption and the start of the offset. If the Option 82 value is set, the offset starts at the beginning
of the whole option 82.
– Offset – is an offset in bytes. It shows the beginning of this parameter in respect to the beginning of the option or
one of its parts
– Length – is the length of the parameter in bytes


85
Inventory 

Switches
This page contains the list of switches available in the system. Every switch description contains its ID, name, comment
and other parameters that allow one to identify this particular switch.

Press to add a new switch.

When adding a new switch, one has to enter
the following parameters:
–Main parameters:
–ID – is an internal switch ID (is assigned
automatically)
– Name – is the switch name in the database (name uniqueness is not checked, but is recommended)
– Actual address – is a field that contains information about the actual address of this particular switch
– Device parameters:
– Type – is a list that allows to choose
one of the existing switch types. Press
to see the parameters
of this switch type and to make sure
that the switch fits those parameters.
– Remote ID – is a DHCP option 82 parameter Remote ID. It is used by the switch to form DHCP requests. The
parameter type is set in the corresponding switch type properties.
– Ports count – is the number of ports in the switch. Choose the appropriate number. This list is created in the
switch type properties on the Switch type page.
– Access parameters – are the switch access parameters. These parameters might be used in firewall rules (RFW
module)
– DHCP options – is a set of auxiliary
DHCP options. If those options are set,
they will be included in the DHCP
response, if they were present in a
corresponding DHCP request.

DHCP pools
This page contains the list of the DHCP pools. The connection between a DHCP pool and a DHCP client or a DHCP
Relay is set in the service link parameters.

Press to add a new pool of IP

addresses. When adding a new pool, one
should set the following parameters:
– Main parameters: – are the basic settings
and the block action type. The basic
settings include:
– ID (is assigned automatically)
– Gateway
– Netmask
– DNS server 1
– DNS server 2
– NTP server
– Domain


86
About 

– Lease time
The block action type defines the DHCP server behavior in case a DHCP request comes from a blocked user (a user
who’s personal account is blocked). This parameter might have the following values:
– Not set – which means that the DHCP server will lease an IP address for both blocked and not blocked users
– Use blocked – is an option that allows one to assign IP addresses from a certain DHCP pool to blocked users.
In order to use this option, one has to select a pool that will be used for treating requests from blocked users. This
option is only available when more than one DHCP pool is registered in the system
– Ignore request – means that DHCP requests coming from blocked users will be ignored by the DHCP server
– Dynamic ranges – is the range of addresses for the current DHCP pool.

– DHCP options – is a set of auxiliary

DHCP options. If those options are set,
they will be included in the DHCP
response, if they were present in a
corresponding DHCP request.

DHCP lease
This page contains the list of active and
expired DHCP leases.
The table has the following columns:
– ID – is an automatically assigned record
number
– IP – is the leased IP address
– MAC – is the client’s MAC address
– Server ID – is the server’s IP address
– Client ID – is a HostName attribute of the
DHCP option 12 from the client’s DHCP request
– Expires on – is the date of the IP address lease expiration
– Updated – is the start date of the IP address lease
– Status – is the lease status. This parameter might have the following values:
– Static – the address has been assigned statically (has been entered in IP group settings)
– Dynamic – the address has been assigned dynamically
– Static, Modified – the address has been assigned statically, after that IP group settings have changed, or it has
neen removed
– Dynamic, Modified – the address has been assigned dynamically, after that IP group settings have changed, or
it has neen removed

About
This group contains two pages:
– About – contains the program version number and contact info of the license holder.


87
Stray pages 

– Licenses – displays list of separate modules’ licenses and their terms of validity. Pressing Read reveals specific
inner parameters and limitations of a particular module.

Stray pages

Payment page
The payment page opens in a separate window and contains the
following interface elements:
– Login – is the user login (view-only).
– Switch internet on – enables switching the Internet status for
the given account to On after making the payment, should the
resulting account balance be positive.
The default setting for this option (on / off) is defined by one of
the interface parameters, see : TurnInternetOn on page 32.
– Account – is a drop-down list for selecting an account, if the
user has more than one of them.
– Amount; – of the payment.
– Currency – of the payment.
– Payment date – is the date when the payment is made.
– Expires on – is the date of expiration of the payment (optional
parameter).
– Payment method – is a drop-down list for selecting one of the registered payment methods. Once the payment
method is set to Loan, the Expires on parameter becomes mandatory.
– Payment document number – is the number of external document (if any) being the reason for the payment.
– Write out a receipt – enables the generation of a receipt for printing on pressing.
– Comment (For administrator, For user) – are arbitrary comments.
– Payment to invoice – is the number of internal invoice (if any) being the reason for the payment. If the payment is
being made according to some internal invoice, the Sum and Currency fields get filled with the values from the said
invoice and turn inactive.
– Send email notification – enables sending an e-mail notification to the user.


88
Stray pages 

Search page
The search page opens in a separate window and contains the following interface elements:

– On the Simple tab one may perform a text search by login or by full name, as well as search by user ID, primary
account ID, IP address, or account balance.
– On the Custom tab one may perform a search by combination of an arbitrary number of conditions including any of
the user’s properties.
– The Link to dealer button opens the interface for linking the user to a dealer, like the similar button on the user
properties page (see : Main parameters: on page 34).
– The Edit button opens the user properties window, like the similar button on the user list page (see Users on
page 33).
– The Add to group button opens the interface for adding selected users to a group, like the similar button on the user
properties page (see : Groups on page 35).
– The New payment button opens the payment window (see Payment page on page 88).

Personal account
User account is an object containing the financial
information. User accounts are created, modified
or deleted via the user details window (see :
Accounts on page 35). A user may have multiple
accounts. 

User account has the following parameters:

– Personal account – ID (is assigned
automatically).
– External account ID – (optional) for
integration with some external system.
– Loan – of the account (may be changed either manually in this window, or by making payments with special method
called Credit).
– Balance – of the account (view-only).
– VAT rate – to be applied before invoicing.
– Sale tax rate – to be applied before invoicing.
– IPTV access card – is the user account IPTV access card number. This field might be empty if the card hasn’t been
generated yet. In that case press to generate an IPTV access card for this user account.


89
Stray pages 

– Requirement payment – is the amount to be paid if the user wants to unblock his account in the current accounting
period. The payment is calculated as follows: the amount on the balance of the user's personal account minus the
amount of all payments that must be made in the current accounting period. The loan amount is not included in the
calculation.
– Internet status – of the account (on / off). The Auto enable inet flag allows one to set up UTM5 to automatically
enable Internet for this personal account as soon as the customer replenishes her account and the account
unblocks.

The flags Don’t charge recurrent fee and Decrease prepaid traffic which were among the account properties
in UTM versions up to 5.2.1-008 have been since transferred to charge policy properties, see Charge policies
on page 46.

– Blocking type; – shows whether the account is blocked, which can be done arbitrarily by the administrator or
automatically by the system. Note that after lifting a manual blocking you have to turn Internet on for that account
(this is done in the same window, see Internet statusabove).
– Block period – (optional) for the administrative blocking, if one is being set.

Unlike the current blocking status, a blocking scheduled for the future is not manifested at all in the account
properties. To look for it, check the corresponding report (see Report on blockings on page 62).

– Unlimited mode (must be used with care) – turns all charges off this account to zero, thus effectively making all
services free.

Tariff link
Tariff link is an object connecting a tariff plan to an account. Tariff links are created, modified or deleted via the user
details window (see : Tariff links on page 36). Prior to tariff link creation, an account has to be selected to associate
the link with.

Tariff link is characterized by the following parameters:

– Current tariff plan – is the tariff plan that is acting now.
– Next tariff plan – is the tariff plan to switch to by the end of accounting period. May be selected at any time during
the current period. Must be compatible with the current plan (see Tariff plans compatibility on page 18). If set to
Do not change, the tariff link together with all its service links will be prolonged onto the next period. If set to Disable
TP (this can be done by editing, but not during the creation of the tariff link), the tariff plan will be disconnected and
all its service links lost.
During an accounting period the next tariff plan ID may be changed multiple times, because the tariff plan will only
actually change at the end of the period.
– Change now – allows to change the tariff plan before the end of the accounting period. The price of the periodic
services will be recalculated in that case.
– Accounting period – is the period of validity of the current tariff plan. Must be selected from the list of accounting
periods (see Accounting periods on page 46) by pressing Select. At the end of the period the tariff plan switch
occurs.


90
Stray pages 

After setting the necessary parameters and pressing the system will prompt to create the service links for the
services having Attach by default checked. Other services must be added later by pressing Add service link in the
tariff link details window.

Service link
Service link is an object connecting a service to an account. Tariff links are created, modified or deleted via the user
details window (see : Service links on page 35). Prior to tariff link creation, an account has to be selected to associate
the link with.
Service link parameters are listed below. The actual set of parameters vary depending on the service type.

One-time service link

Service link of this type has the following parameters:
– Name; – of the service (read-only parameter).
– Charge time – at which the charge-off for the service is going to be
made. If the date is set in the future, the charge-off will be made exactly
then. Otherwise, i. e. if the date is set in the past, the charge-off will be
made right after the creation of the service link. The date is interpreted
according to the local time of the computer on which the administrator’s
interface is running.
– Cost, % – is the actual cost of the service for this particular user. It is specified in percents relative to the base cost
of the service, and may be altered arbitrarily.
After charge-off the one-time service link is removed.
Parameters of the service itself are described in One-time service on page 49.

Periodic service link

Service link of this type has the following parameters:

– Service name;
– Accounting period; – to which the service link refers.
– Start date – since when the service is provided to the user.
– End date – since when the service stops being provided to the user. By that date the service link is deleted.


91
Stray pages 

– Charge policy. – One can select a charge policy to apply to the service link. Press to see the chosen
charge policy parameters (for more information about the charge policy see Charge policies on page 46).
– Charged – the amount of all charges applied to user’s account during the current accounting period. Press
to open a periodic service statistics window. The button becomes active after saving the service link:

– Cost, % – is the actual cost of the service for this particular user. It is specified in percents relative to the base cost
of the service, and may be altered arbitrarily. This affects only the periodic component of the service cost. 

Correction is made at the end of a service period It uses the correction field value at the moment of correction

After saving the service link, this field shows the current coefficient if the service is linked to a coefficient scheme
(see Basic system objects: Coefficient scheme on page 23). Press to see the link to a schedule: 

This window allows one to change the coefficient scheme, its start date and the schedule for the cirrent service link.
– Coefficient scheme – select a scheme for the current service link. The default scheme is the one connected to the
selected service.
– House – select address. This field may be useful when the actual service provision address differs from the one,
specified in user properties, on the Contacts page. Press to see the list of houses that are registered in
the system (see Administrator’s interface: Buildings on page 59).

If the selected address is the same as in the one specified in the user properties, House field will become empty
after saving the service link.


92
Stray pages 

IP traffic service link

Service link of this type has the same parameters as the periodic
service link (see Periodic service link) plus the following specific
parameters:
– IP groups – that define the user’s networks. Traffic identification
for further evaluation is based on the IP group parameters together
with NetFlow records.
If the user is linked with a building, the first available address from
the zone associated with this building stands for network address.
press to add a new IP group.
An IP group has the following parameters:




– IP settings tab:
– IPv4/IPv6 subnet – is the IP address and mask of the group’s network.
See IP addresses on page 25for the formatting details. These
parameters are cached by UTM5 RADIUS.
The Dynamic flag will be set if the IP group is temporary and has been
created automatically for an IP address, assigned by the DHCP server




– RADIUS settings tab:

– Login and Password. – Upon authorization with these login and
password, the user is granted the first free IP address from the network
specified in the properties of the IP group. If there are no free
addresses left, authorization is denied.
Pressing while creating an IP group generates a random
password.
Login is subject to the same requirements as the general UTM5 user
login (see Adding users on page 34). 
These parameters are cached by UTM5 RADIUS.
– RADIUS pool – is one of the registered IP pools. Upon authorization the user will be assigned an address from
this pool.

After the session is terminated, the IP address will remain assigned to the user for a certain period of time. This
time period is determined by the dynamic_ip_unlink_timeout parameter that can be found on the Settings page
in the Parameters list group.

– Allowed CID – is the regular expression against which the value of Calling-Station-ID attribute of the
authorization request is checked. If the attribute is not set (not supported by NAS) or does not match the regex,
authorization is denied.
This parameter is cached by UTM5 RADIUS.


93
Stray pages 

– DHCP settings tab:

– MAC address – is the DHCP client's MAC address. This parameter is
used by the DHCP server to issue an IP address
– Switch – is a parameter that lets one link an IP group to a certain
switch. UTM5 DHCP uses it for providing IP addresses as a DHCP
option 82 parameter.
– Port – is a parameter that lets one link an IP group to a certain switch
port. It is also used as a DHCP option 82 parameter for providing IP
addresses.
– VLAN ID – is an ID for DHCP client’s VLAN.
– Dynamic DHCP pool – is a pool that will be used to provide an IP address and network settings to the DHCP
client (see DHCP pools on page 86). This parameter is mandatory if a static IP address is not set up.
– Additional settings tab:
– NetFlow provider – is the firewall providing NetFlow data. If this
parameter is set, then only the traffic data coming from this provider will
be associated with this IP group.
– Not VPN IP group – is a marker of membership in a non-VPN group.
Is optional and is not considered in any rules.
– Do not affect firewall rules – forbids to apply the firewall rules for this
group.
– Quotas – that determine upper limit of traffic to consume. Once the limit
is exceeded, the user gets blocked till the end of period. Quotas may be set for
different traffic classes separately.
In this case each of them is equally capable of triggering the user’s blocking.
If the end date of an accounting period gets changed while a user stays blocked
by quota, the end date of blocking does not change with it.
Parameters of the service itself are described in IP traffic service on page 50.
After adding an IP traffic service link, one can set up additional RADIUS parameters on the Service links page.
Choose a service link which you want to set up the additional RADIUS parameters for and press the
button. A additional RADIUS parameters window will open (for a more detailed description
see Additional RADIUS attributes on page 71). One can also add additional attributes to Dialup and Telephony
service links.

Press to add prepaid traffic. In the popup window choose

a traffic class and press . Enter the desired amount of traffic and
press .

Adding prepaid traffic is only possible when the prepaid traffic has not been
consumed yet. When the prepaid traffic is consumed, one cannot add prepaid
traffic any more.


94
Stray pages 

Hotspot service link

Service link of this type has the same parameters as the periodic service link
(see Periodic service link on page 91) plus the following specific parameters:
– Login, Password – are used for authorization in the user web interface.

Hotspot login may not start with a digit. Parameters of the service itself
are described in Hotspot service on page 51.

Dialup service link

Service link of this type has the same parameters as the periodic service link
(see Periodic service link on page 91) plus the following specific
parameters:
– Login, Password – are to be used for the user’s authorization on the
access server. On successful authorization the server establishes
connection and issues the dynamic IP from a pool. These parameters are
cached by UTM5 RADIUS.
While accepting the login, UTM5 RADIUS may automatically cut off the
prefix defined by the radius_realm parameter (see Settings available in
the administrator’s interface on page 117).
– Allowed CID – is a regular expression to check against the
Calling-Station-ID attribute of the authentication request. These
parameters are cached by UTM5 RADIUS. If the regex is set, but the
attribute does not match it or is missing, the authorization is denied.
– Allowed CSID – is a regular expression to check against the
Called-Station-ID attribute of the authentication request. These parameters are cached by UTM5 RADIUS. If the
regex is set, but the attribute does not match it or is missing, the authorization is denied.
– Callback allowed – instructs the RADIUS server to check the incoming login (the part after colon) against the
Callback standard. This parameter is cached by UTM5 RADIUS. Login is the part coming after colon. These
parameters are cached by UTM5 RADIUS.
– Ringdown allowed – instructs the RADIUS server to check the incoming login for all non-Callback calls. These
parameters are cached by UTM5 RADIUS.
If neither Callback allowed nor Ringdown allowed are set, the authorization with the given login and password is
denied.
Parameters of the service itself are described in Dialup service on page 52.

Telephony service link

Service link of this type has the same parameters as the periodic service link (see Periodic service link on page 91)
plus the following specific parameters:
– Telephone numbers – is the table with phone numbers, containing the following information on each entry:
– Login – to be used for identification of the service link.
– Incoming trunk, Outgoing trunk, PBX ID – against which every call must be checked (if set).
– Telephone – number issued to the user upon registration (if set).
– Password – to be used for the user’s registration or a call authorization.


95
Stray pages 

– Allowed CID – which is a regular expression to check against the Calling-Station-ID attribute of the
authentication request. If the regex is set, but the attribute does not match it or is missing, the authorization is
denied.

The set of parameters identifying the telephony service link (which are: login, incoming trunk, outgoing trunk, and PBX
ID) must be unique. In each set at least one of these parameters must be filled, i.e. non-empty. If a call matches several
service links by some parameters, the one with the greatest number of matches is selected.
Parameters of the service itself are described in Telephony service on page 53.

IPTV service link

Service link of this type has the same parameters as the periodic service link (see Periodic service link on page 91)
plus the following specific parameters:
– Custom options – additional data for the service link like access card number, subscription ID, etc.


96
Tray icon 

– IPTV access card (for NetUP IPTV) – is the user’s IPTV access card number. If this card was not created earlier,
one can create it in this window. Press to create a new access card.

For more information on access card, see the IPTV administrator’s manual.

Video on demand service link

Service link of this type has the following parameters:
– Start date – since when the service is provided to the user.
– Cost, % – is the actual cost of the service for this particular user. It is specified in percents relative to the base cost
of the service, and may be altered arbitrarily. This affects only the periodic component of the service cost.

Correction is made at the end of a service period and it uses the value of the filed by the end of the period

– IPTV access card – is the user’s IPTV access card number. If this card was not created earlier, one can create it
in this window. Press to create a new access card.

For more information on access card, see the IPTV administrator’s manual.

Tray icon
When the control center is working, it is represented by an icon in the system tray. . The icon has a context menu
of its own, which contains the following items:
– Main window – activates the main window of the program.
– Frames – select one to move on top – – (active when there are multiple open windows) selects and activates any
of the control center windows, except the main one.


97
Tray icon 

– Processes – select one to cancel – (active when there are processes running; at that, the icon changes to )
selects and terminates a process. May be worthwhile if the process is taking longer than expected.
– Cancel printing – (active when there is a printing task running) terminates printing.
– Exit – stops the control center.


98
Introduction 

Usage examples 9
Introduction
This chapter contains typical scenarios of UTM usage. All actions are performed via the interfaces of the control center
which itself is described in Installation and startup. Complete description of the control center interface pages is given
in Administrator’s interface on page 31.
To perform the initial setup of the UTM system one generally needs to do the following:
– Create accounting periods (see Creating accounting periods on page 99);
– Create traffic classes (see Creating traffic classes on page 101);
– Create services (see Creating services on page 101);
– Create users (see Creating users on page 102);
– Assign services to users (see Creating service links on page 105and Creating tariff links on page 107).

Installation and startup

1. Download the administrator’s interface located in the client’s personal cabinet on 
https://www.netup.tv/en/utmoffice (under Downloads > file utm_admin.zip).
2. Unpack the archive on the administrator’s workstation (i.e. the computer which will be used to control the system).

Java Runtime Environment (JRE) version 8.0 (Java 1.8.x) or above is required in order to use the control center
JRE distributive is available for free at java.com .

3. Start the control center either by clicking on the file utm_admin.jar or from the
command line by executing 

java -jar utm_admin.jar

The login dialog window will appear

4. Enter the IP address and colon-separated port number to connect to. If the port
number is omitted, the default value of 11758 is assumed.
5. Enter the login and password. By default, login is init and password is init.
6. In the Settings group of parameters select the language to use.

Note that the selected language is not applied immediately to the login dialog itself. Instead, the language switch
occurs on the next launch of the program.

7. Check Save options if you want to save the parameters just entered (except for password) in the settings file for
use during subsequent launches. Check Save password if you also want to save the password as well.

It is highly recommended to change the password for the system user init immediately after logging in for the
first time (see Administrator’s interface: Change password on page 85).

Creating accounting periods

Accounting period (see Basic system objects: Accounting periods on page 18) is a period of time to which various
periodic activities, including charge-offs, are related.
To create an accounting period:
1. Click Accounting periods on the left pane under Tariffication. The list of available accounting periods will
appear.


99
Creating time ranges 

2. Press to create a new accounting period. An

Accounting period window will show up.
3. Select the starting date of the period.
4. Select the type of the period (daily, weekly, monthly, quarterly,
annual, or custom; in the last case enter also the duration).
5. Press to finalize the creation of the new accounting
period.
When the period finishes, a new one of the same type is created
automatically.

Creating time ranges

Time range (see Basic system objects: Time ranges on page 23) is a period of time, or a set of such periods, used
by the system to define time-dependent behavior.
To create a time range:
1. Click Time ranges on the left pane under Tariffication. The list of available time ranges will appear.
2. Press to create a new time range. A Time range window will show up.
3. Set the name of the new time range (e.g Night).
4. Set the new range’s priority to 1 (the higher the number, the higher the priority).
5. In the visual editor select the night hours.

Use Shift in order to select multiple cells at a time. E.g. to select the whole time range select 00 hours on Sunday,
press Shift and select 23 hours on Saturday.

6. Press to finalize the creation of the new time range.


100
Creating traffic classes 

Creating traffic classes

To classify traffic (see Basic system objects: Traffic classes on page 17), the system contains two predefined
classes, namely Incoming and Outgoing. The Incoming class has ID set to 10 and consists of a single subclass with
its Destination parameter set to the address and mask of the local network. The Outgoing class has ID set to 20 and
a single subclass with local address for Source. You may want to create additional classes, say, to charge different
prices for the traffic at different times of day.

In order to create traffic classes with time-dependent condition of membership, one has to create the
corresponding time ranges beforehand, see Creating time ranges on page 100.

Creating new traffic classes:

1. Press Traffic Classes on the left pane under Tariffication. The list of existing traffic classes will appear.
2. Press to create a new traffic class. The Traffic class window will show up.
3. Set the traffic class ID to 15.
4. Set the traffic class name to Night Incoming.
5. Select Night in the Time range drop-down list.
6. Press above the list of traffic subclasses. The traffic subclass properties window will show up.
7. In the Addressee group enter the IP address and subnet mask for local network, in the Source group enter the
source network address and subnet mask (e.g. enter 0.0.0.0/0 if source of the traffic doesn’t matter) and press
.

8. After creating the subclass press in the Traffic class window to finalize the creation of the new traffic
class.
9. In a similar manner create the class Day Outgoing with the following properties:
– ID: 25;
– Time range: Day (supposed you’ve already created this time range);
– Subclass properties: enter local IP address/mask into the Source group.
1. In a similar manner create the class Internal with the following properties:
– ID: 1000;
– Time range: leave default value (Not defined);
– Subclass properties: enter local IP address/mask into both the Source and Destination groups.

Creating services
may contain services of various types (see Basic system objects: Services on page 18) which in turn may require
some type-dependent prerequisites. In particular, to create an IP traffic service, one has to create the necessary traffic
classes in the first place (see Creating traffic classes on page 101).
To create a new IP traffic service:
1. Click Services on the left pane under Tariffication. The list of existing services will appear.
2. Press to create a new service. The Service window will appear.
3. Enter the service name.
4. Set the service type to IP traffic. A set of additional shortcuts will appear on the left pane.
5. In Service parameters enter the periodic fee and select a charge-off method (at the beginning, or at the end of an
accounting period, or flow method).
6. In Tariffication borders press above the list of borders.


101
Creating users 

7. In the window that appears, select a traffic class for the border, enter the border position in bytes (0) and cost for
traffic exceeding the border in currency units per megabyte. Press

8. In order to add prepaid traffic to the service, press above the list of prepaid units in Prepaid traffic.

9. In the window that appears select the class of prepaid traffic and enter its volume in bytes. Press

10.Press in the Service window to finalize the creation of the new service.

Creating users
New user account is created via the dialog window for adding users (called by pressing the button in the list of users).
Required information is a user login and a password. On creation of a new user account a password is being generated
automatically, yet it may be changed. A personal account is being created along with the user account.

To create a new user:

1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Press The user properties window will show up.
3. In the user properties window enter the user’s login and (if necessary) personal information.
4. Press Apply. A set of additional shortcuts will appear on the left pane.
5. Select Other on the left pane. In the list Currency select the currency for transactions with the user.
6. Create service and tariff links as described in corresponding examples (see Creating service links on page 105,
Creating tariff links on page 107).
7. Press in user details window To finish creating a new user

When a user account has been created, one may start adding services. See Creating service links on page 105and
Creating tariff links on page 107for details.

Removing a user
To remove a user:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. If the user’s accounts have some service links attached to them:
3.1. On the left pane of the user properties window open Service links under Tariffication. The list of service links
will appear.
3.2. Remove each service link by selecting it, pressing and selecting OK in the confirmation window.


102
Creating account 

3.3. Repeat the previous step with the other user’s accounts, if any.
4. If the user’s accounts have some tariff links attached to them:
4.1. On the left pane of the user properties window open Tariff links under Tariffication. The list of tariff links will
appear.
4.2. Remove each tariff link by selecting it, pressing and selecting OK in the confirmation window.
4.3. Repeat the previous step with the other user’s accounts, if any.
5. Press to close the user properties window.

6. Select the user in the list and press .

The user can not be removed while still having some service or tariff links attached.

Creating account
The user’s primary account is created automatically together with the user. Besides, an arbitrary number of additional
accounts may be created afterwards.
To create an additional account:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. On the left pane of the user properties window open Accounts under Tariffication. The list of user’s accounts
(initially containing only one account) will appear.
4. Press The account properties
window will show up.
5. Select the Internet status for the account being
created (On / Off).
6. Select Credit for the account (a sum to be put
on this account upon creation).
7. Select Block ID for the account (see the list in
Accounts on page 16). In case of blocking
type other than No you may check the Block
period flag and set the time span for the
blocking to persist.
8. Enter the tax rates, namely VAT rate and Sale tax rate.
9. If necessary, check the Unlimited mode flag.
10.Press to finalize the creation of the new account.

Removing an account
To remove an additional account:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. If the account has some service links attached to it:
3.1. On the left pane of the user properties window open Service links under Tariffication. The list of service links
will appear.
3.2. If another account is selected in the drop-down list, select the one you need. The list of service links will switch
to that of the selected account.
3.3. Remove each service link by selecting it, pressing and selecting OK in the confirmation window.


103
Creating a charge policy 

4. If the account has some tariff links attached to it:

4.1. On the left pane of the user properties window open Tariff links under Tariffication. The list of tariff links will
appear.
4.2. If another account is selected in the drop-down list, select the one you need. The list of service links will switch
to that of the selected account.
4.3. Remove each tariff link by selecting it, pressing and selecting OK in the confirmation window.
5. On the left pane of the user properties window open Accounts under Tariffication. The list of user’s accounts will
appear.
6. Select the required account in the list and press .
7. Press OK in the confirmation window 
to finalize the deletion of the account.

The user’s primary account can not be removed.

Creating a charge policy

To create a charge policy:
1. Open Charge policies page in the Tariffication group of pages.
2. Press This will open a charge policy setup window.

3. Enter charge policy’s name.

4. Check all flags in the Recalculation on service link creation group (for more information on recalculation see
Basic system objects: Charge policy on page 22).
5. Check the Periodic fee checkbox in the Don’t charge without block group if you want to charge a fee while the
user’s personal account is blocked. The fee is charged from the user which was blocked during the entire


104
Creating service links 

accounting period. 

This condition only works if the Recalc periodic fee option is selected for the block type that is used for
blocking the user’s personal account

For example, a user is blocked with the User’s block. To charge the fee while the user is blocked, check two
checkboxes in the Charge policy: the Periodic fee checkbox in the Don’t charge without block group and the
Recalc periodic fee checkbox in the Recalculation on block group in the User tab.

6. Check the checkboxes in the Recalculation on block group as needed. Switch to another Block type to check the
checkboxes for all the rest block types.
– Do not charge periodic fee
– Recalc periodic fee
– Decrease prepaid traffic
– Recalc prepaid telephony
7. In order to set up the parameters for another bocking type, switch to the corresponding tab.
8. In the next group - Repay, check the events that you want to be coupled with refund when excessive amount of
money was withdrawn from the user’s account.
9. Check the Set system block on funds lack checkbox in the System block settings group.
10.Press to finish creating the charge policy.

Creating service links

Service link is a system object linking a service to a user’s account. Besides the service and account, an accounting
period is required to create a new service link (see Creating accounting periods on page 99).
To create a new service link:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. On the left pane of the user properties window open Service links under Tariffication. The list of service links
attached to the primary account will appear.
4. Select another account if necessary. The list of service links will
switch to that of the selected account. 




105
Creating a tariff plan 

5. Press The service selection window will show up. 




6. Select the service from the list and press . The service link
properties window will show up.
7. Press and select the accounting period for the service
link.
8. Select the starting date for the service.
9. Select the ending date, or check the Infinite date flag.
10.Select a charge policy.
11.Set the service cost correction if necessary.
12.Press to add an IP group.

13.In the IP group window go to DHCP settings tab and choose a

dynamic DHCP pool which will be used for giving an IP address to user.
You may also choose switch and port to which the user is connected.

14.Press to finalize the creation of the new service link.



Creating a tariff plan

A tariff plan is an entity that combines multiple services. Using tariff plans is convinient because one can add a bunch
of services to a user in one operation (by selecting a tariff plan). In order to add a service to a tariff plan one has to create
a service template first (see Service templates on page 55).
In order to create a tariff plan:
1. Open Tariff plans page (Tariffication > Tariff plans) and press .
In the popup window enter the tariff name and a comment (optional), then
press .

2. Double click the created tariff plan or select it and press .




106
Creating tariff links 

3. In the tariff plan properties window press . A window with a list of

service templates will appear. 











4. Select a template and press . A service settings

window will appear. 





5. Tweak the service settings as needed. E.g. In order to

prevent a service from automatically activating as the tariff
plan is attached to a user, uncheck the Attach by default
checkbox. Press The service will be added to the
tariff plan.

Any changes in the service properties only affect the

service that is a part of the service plan and do not affect
the service template (parent service).

6. In the same way one can add more services if needed. Press to
finish creating a tariff plan. A service plan may be edited later on.

Creating tariff links

Tariff link is a system object linking a tariff plan to a user’s account. Besides
the plan and account, an accounting period is required to create a new tariff
link (see Creating accounting periods on page 99).
To create a new tariff link:
1. Press Users on the left pane under Users & Groups. A list of existing
users will appear.
2. Select the user in the list and press . The user properties
window will show up.
3. On the left pane of the user properties window open Service links under Tariffication. The list of tariff links
attached to the primary account will appear.
4. Select another account if necessary. The list of tariff links will switch to that of the selected account.


107
Linking a user to a house 

5. Press The tariff link properties window

will show up.
6. Select the Current tariff plan from the drop-down
list.
7. Select the Next tariff plan from the drop-down list,
or leave the default choice Do not change. 

8. Press and select the accounting period for the tariff link.

9. Press to finalize the creation of the new tariff link.

10.If the current tariff plan contains some one-time services having their Attach by default flag set, each of those will
be manifested by a prompt window. Select the date and time of the charge and press .

Linking a user to a house

UTM5 system is capable of maintaining a list of houses (see Reference book: Buildings on the left pane). To link a user
to a house:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. On the left pane of the user properties window open Contacts under User. The user contacts page will appear.
4. Press next to House and select the building from the list.

5. Press to close the list of buildings.

6. Press in the user properties window to save the changes.

Linking a user to a bank

UTM5 system is capable of maintaining a list of banks (see Reference book: Banks on the left pane). To link a user to
a bank:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up.
3. On the left pane of the user properties window open Additional under User. The additional user information page
will appear.
4. Press next to Bank and select the bank from the list.

5. Press to close the list of banks.

6. Press in the user properties window to save the changes.

Making payment
To make a payment to a particular account of the given user:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.


108
Creating dealers 

2. Select the user in the list and press . The payment

details window will show up.
3. If necessary, select another account from the drop-down list.
4. Select the payment currency from the list.
5. Enter the sum of payment.
6. Enter the payment date or leave the default value (current date).
7. Enter the payment expiration date or leave the default value (never).
8. Enter the arbitrary comments for the administrator and for the user.
9. Select the payment method from the list.
10.If the payment is being done on demand of some external
document, enter the number of that document.
11.If the payment is being done on demand of some internal invoice,
select the number of that invoice from the list.
12.Press to finalize the payment.

Creating dealers
To create a new dealer:
1. Press Dealers on the left pane under Users & Groups. A list of registered dealers will appear.
2. Press The dealer properties window will show up.

3. Enter the dealer’s login and the full name.

4. Copy the generated password for handing it over to the operator, or enter the new password twice.
5. If appropriate, specify a subnet to allow the dealer’s authorization from.
6. Press to finalize the creation of the new dealer.

Setting dealer’s permissions

To permit dealer’s access to certain system objects:
1. Press Dealers on the left pane under Users & Groups. A list of registered dealers will appear.
2. Select the dealer in the list and press . The dealer properties window will show up.
3. On the left pane of the dealer properties window open Users under Permissions. The list of users will appear.


109
Linking users to dealers 

4. In the Permissions granted column mark the check boxes corresponding to the users of your choice, in order to
enable the dealer with the access to these users.

Note that the users (unlike other entities) are attached to dealers in exclusion mode, i.e. each user may be
attached to only one dealer. The users already attached to other dealers have their permission check boxes
disabled.

5. In a similar way set up the dealer’s access to other entities on the pages Accounting periods, Services, Tariffs,
and Houses.
6. Press to save the changes.

Linking users to dealers

Besides the way described in Setting dealer’s permissions, the dealer’s access to a user may be set up as follows:
1. Press Users on the left pane under Users & Groups. A list of existing users will appear.
2. Select the user in the list and press . The user properties window will show up having by default its
Main page open.
3. Press Link to dealer. A list of registered dealers will show up.
4. Select the dealer from the list and press to link the user to the dealer.
5. Close the user properties window.
The Link to dealer button with similar functionality may also be found on the search page (see Search page on
page 89).

Creating firewalls
To create a new firewall:
1. Press Firewalls on the left pane under Settings. The list of existing firewalls will appear.

2. Press The Firewall window will show up.

3. In the Type drop-down list select Local if the commands are going to be executed
locally, or Remote Cisco for execution over rsh.
4. Enter the firewall Name. Make sure that no other firewall with the same name
exists in the system.
5. If the firewall is about to be used in the properties of IP traffic service link as
NetFlow provider, enter its IP address in the IP input field.
6. If Type was set to Remote Cisco, enter Login for rsh authorization.
7. Enter arbitrary Comments.
8. Press . New firewall will be created.

Creating firewall rules

To create a new firewall rule:


110
Creating firewall rules 

1. Press Firewall rules on the left pane under Settings. The list of registered firewall rules will appear.

2. Press The Firewall rules window will show up.

3. Enter Comment to be able to tell this rule from the others in the list.
4. In the Firewall drop-down list select the firewall to run the command on, or Any to apply the command to all
firewalls available at the time of its execution.
5. In the Execute for group either set the All users check box, or set one or more of the following conditions to define
the applicability domain:
– User ID;
– Group name (select from the drop-down list);
– Tariff name (select from the drop-down list).
If more than one condition is checked, their union is used. To use the intersection of conditions, check All
parameters match.

Firewall rules associated with the global system events (Raw traffic file closed and Log file closed) require
that the All users option must be checked.

1. In the Execute when group select one or more events to initiate the rule in question using the drop-down list of
events and the Add and Remove buttons.
2. Enter the command template in the Firewall rule field. Use the necessary variables by selecting them from the
drop-down list (see UTM5 RFW: Variables on page 138) and pressing Insert. On execution the variables are
substituted with their corresponding values. The set of available variables depends on the selected initiating events
(see the list in UTM5 RFW: Events on page 143). Attempts to use the non-available variables cause warnings.

3. Press . New firewall rule will be created.


111
Introduction 

System core 10
Introduction
Core of the billing system is a basic module responsible for the database access. The core provides access to it and
processes incoming information under the internal rules (such as tariffication, periodical charge-offs, etc). The core is
a separate multithreaded process functioning in a user-operated mode. Due to its structure the core blends in with
multiple-processor architectures and uses all resources evenly at high workloads.

DMS

Initialization module Database connections

Database verifier
system user URFA server URFA clients
Scheduler
Secondary
aggregation Stream server RADIUS, rfw
storage
Tarrifier
NXT v.1 и NXT v.2
NXT clients
Primary servers
aggregation
storage

Detailed Saving DBA Function handlers

Соединения с БД
Service link
statistics detailed
classifier
files statistics
Traffic classifier
Queue manager

Inner cache
Log files Logging module NetFlow buffer Transaction
Event handlers
handlers

NetFlow provider

Рис. 3. UTM core schematics (since v. 5.3-004)

Main Components of the Core

URFA request handler (UTM Remote Function Access) is a server that invokes remote procedures. It receives
connections of clients and executes requested commands in the core. This component serves mainly as an organizer
of the user and administrator interfaces.
NetFlow buffer receives traffic data in NetFlow format version 5.7, 9, and 10 (IPFIX). Devices that do not support
statistics delivery via these protocols must rely on some auxiliary utility to convert their output into compatible format.
Traffic classifier is a core module that sorts traffic into classes according to characteristics defined in system settings.
These characteristics may be specified via the UTM control center.
Traffic information for one customer, that hasn’t been tariffed, is stored in the primary store. After tariffication this
information is extracted from the primary store and is placed to the secondary store. The customer's account is charged
for the cost of the traffic stored in the secondary store when the cost of the traffic exceeds a certain amount, when it
reaches the storage time limit (Settings available in the administrator’s interface on page 117), when the price of
the traffic changes (e.g. when the traffic price depends on the amount consumed), when the core receives a SIGHUP
signal and when an accounting period is being closed.
The business logic module is responsible for tariffication of all services, including IP traffic transmission. It converts
amount of services consumed into monetary equivalent, taking into account all dependencies defined by system
administrator.


112
Startup 

The log file keeps all records of UTM functions. It provides the administrators with all sorts of diagnostic information
about system failures.
The database access module is a united DB interface which transfers intrasystem data requests into requests to an
external database. It is an abstraction level giving the UTM independence of any particular DBMS.
Data are received via NFBuffer and URFA. Input data are read from the database when the system is launched.

Changes made directly in the database afterwards may cause uncontrolled behavior of the system.

NetFlow data go to the business module where they are processed and all necessary charge-offs are calculated. At
peak workloads NetFlow can be buffered to reduce possible losses. Raw NetFlow data are stored in files. At startup
this DB module is started in a separate thread with (if possible) high priority.

Startup
core executable file is /netup/utm5/bin/utm5_core.
Possible command line parameters are:

-p <path> Path to the PID file

-c <path> Path to the config file
-v Version number and parameters information

The following options for utm5_core startup are available:

1. Direct start of the utm5_core executable with necessary parameters;
2. Start on watchdog with start parameter:

/netup/utm5/bin/safe_utm5_core start

The script will restart utm5_core automatically on failure;

3. Start via the automatic startup script (recommended).
On Linux:

/etc/init.d/utm5_core start

On FreeBSD or Solaris:

/usr/local/etc/rc.d/utm5_core.sh start

To stop the utm5_core and the watchdog script, execute:

on Linux –

/etc/init.d/utm5_core stop

on FreeBSD or Solaris –

/usr/local/etc/rc.d/utm5_core.sh stop

Core settings
System core parameters may be set up in the following ways:
– Via the config file;
– Via the administrator’s interface (see for more detail).
Config file parameters are used during the initialization of the system core and other components. Any changes to these
parameters are applied after the next restart.


113
Core settings 

Interface parameters, on the contrary, are related to the system’s behavior after startup and may be changed at any
moment, unless stated otherwise. The changes are applied immediately.

Configuration file
Config file used by the UTM5 system core is located at /netup/utm5/utm5.cfg.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
Below is the list of all possible parameters.
Database-related parameters:

Parameter Possible Default value Description

values
database_type mysql, postgres Mandatory Database type
parameter
database string Mandatory Database name
parameter
database_host string localhost Database host address
database_login string current user’s Database access login
login
database_password string empty string Database access password
database_sock_path string /tmp/mysql.sock Path to a unix-socket used for the database
(a) server connection. Should be used only for
MySQL database and only if
database_host is not defined or is equal to
localhost

database_port (a) String 3306 Port number for database access

dbcount Number from 2 to 6 Number of database connections open

64 simultaneously by the billing system core for
user operations
dbcount_sys Number from 2 to 4 Number of database connections open
64 simultaneously by the billing system core for
system operations
database_reconnect_ Integer number 5 Number of database connection attempts in
count case of failure. Also, the number of repeated
SQL requests in case of failure
database_reconnect_ Integer number 2 Delay in seconds before repeated connection
sleep attempt or SQL query

database_charset (a) Encoding utf8 Database connection encoding

specification
string
verify_database enable, disable enable Verify database before starting the UTM5 core
verify_archive_tabl enable, disable disable If the database verification is enabled, also
es verify archived tables
verify_database_ind enable, disable disable Verify indexes before starting the UTM5 core
ex


114
Core settings 

a. Is only good for MySQL

URFA-related parameters:

Parameter Possible Default value Description

values
urfa_bind_host (a) IP address of the 0.0.0.0 IP address of the server listening to Stream
interface, or requests
0.0.0.0
urfa_bind_port Number from 1 to 11758 Port listening to Stream requests
65534

a. May hold multiple values

Stream-related parameters:

Parameter Possible Default value Description

values
stream_bind_host IP address of the 0.0.0.0 IP address of the server listening to Stream
interface, or requests
0.0.0.0
stream_bind_port Number from 1 to 12758 Port listening to Stream requests
65534

NXT-related parameters:

Parameter Possible Default value Description

values
nxt_bind_host IP address of the 0.0.0.0 IP address of the server listening to NXT v.1
interface, or
0.0.0.0
nxt_bind_port 1 to 65534 11777 Port listening to NXT v.1
nxt_v2_bind_host IP address of the 0.0.0.0 IP address of the server listening to NXT v.2
interface, or
0.0.0.0
nxt_v2_bind_port 1 to 65534 11778 Port listening to NXT v.2
iptv_cluster_host IP address not set NetUP cluster core IP address
iptv_cluster_port 1 to 65534 50500 Port that IPTV cluster core is listening to for
incoming connections

NetFlow buffer parameters:

Parameter Possible Default value Description

values
nfbuffer_host string 0.0.0.0 IP address of the server listening to NetFlow
nfbuffer_port string 9997 Port listening to NetFlow
nfbuffer_bufsize Integer Set by OS Size of the UDP socket buffer used to accept
NetFlow


115
Core settings 

Traffic counting parameters:

Parameter Possible Default value Description

values
classifier_traffic_ Path to file /netup/utm5/db/ File to store traffic information when UTM5
file traffic.dat core stops

Document generation parameters:

Parameter Possible Default value Description

values
doc_path File path /netup/utm5/doc *.odt file storage directory
tmp_path File path /tmp Temporary files storage
libreoffice_path File path /usr/bin/libreoffice LibreOffice executable path
max_upload_size Size in bytes 1000000 Maximum size of document template /
contract file for upload

Logging parameters (for more details see System description: Logging on page 13):

Parameter Possible Default value Description

values
log_level Number 1 Level of messages to be written to the main
0 to 3 log file
log_file_main Path to file standard error Main log file
stream
log_file_debug Path to file standard error Debugging log file
stream
log_file_critical Path to file standard error Critical log file
stream
log_file_verificato Path to file /netup/utm5/log/ Database verifier log file
r ve-rificator.sql
syslog_name string not set Log entry prefix (when logging to syslog is
enabled)
rotate_logs yes, on, enable (rotation off) Enables log files rotation

max_logfile_count (a) number (unlimited) Maximum number of log files to keep

max_logfile_size (a) Size in bytes 10485760 Maximum size of log file

core_pid_file Path to file /var/run/utm5_cor PID file

e.pid

a. Works if log file rotation is enabled.

Stack parameters:

Parameter Possible Default value Description

values
thread_stack_size Size in bytes (not 8388608 Business logic thread stack size
less than 65536)
rpc_stack_size Size in bytes (not Not set URFA server thread stack size
less than 65536)


116
Core settings 

License parameters:

Parameter Possible Default value Description

values
ssl_cert_file Path to file /netup/utm5/c Certificate file
ert.crt
ssl_privkey_file Path to file /netup/utm5/p Private key file
rivkey.pem
ssl_privkey_passphr String empty string Private key password
ase

Settings available in the administrator’s interface

One can find settings available to edit from the administrator's interface in the Settings group of pages Parameters
are divided into several settings groups:
– Tarrification settings
– Card user settings
– Notification settings
– SMTP protocol settings
– Invoice document settings
– Other settings
– RADIUS protocol settings

Select a settings group and double click it or press . This will open a popup window with a list of
editable parameters:

If a parameter is underlined hover over it to read a help message:

The Traffic aggregation timeout and Minimum traffic charge threshold parameters define the rate at which the
customer's personal account is being charged.

These parameters are considered simultaneously. Customer’s personal account is charged when either
condition is satisfied: Traffic aggregation timeout is exceeded or the amount of traffic has reached the threshold.


117
Core settings 

The lower these parameters, the faster will grow the tables that store charges statistics. Those tables are the
largest in the database and may require table archiving in order to reduce the DB load (see Archiving of tables
on page 201).


118
Introduction 

UTM5 RADIUS 11
Introduction
UTM5 NetUP RADIUS server is an application intended for real-time processing of the incoming requests using
Remote Authentication Dial In User Service (RADIUS) protocol as described in RFC 2865, RFC 2866 and RFC 5176.
RADIUS protocol serves for secure authorization, authentication and accounting between NAS and authorization
servers.
This protocol makes it easier to manage large numbers of NAS. When there are several management devices that
users need to have access to in one network and each device stores user data for all the users in the network, it
becomes very hard to manage such a system. This can be solved by installing a common authorization server so that
all the network devices could query it over a standard RADIUS protocol. In this case one may use NAS from any
vendors that support RADIUS protocol.
Besides that, the protocol is applicable to collect information on consumed services, such as connection time, amount
of traffic, user’s IP address, etc.
NAS setup is described in Administrator’s interface: NAS list on page 70
UTM5 RADIUS interacts with the UTM5 core using Stream protocol.

One instance of UTM5 core may work with only one RADIUS server.

RADIUS server is a part of several different modules that require separate licenses. To verify the availability of the
licenses and their terms of validity, see : Licensesin the UTM5 administrator’s interface and check for at least one of
the following items in the list: VPN/Dial-up module, Telephony module, or Hotspot module.

RADIUS protocol description

In case if the NAS is intended to interact with UTM5 RADIUS over the RADIUS protocol, it does not keep its user base.
On user’s connection, NAS makes an Access-Request call.
UTM5 RADIUS considers whether to permit a connection, and responds to the NAS with Access-Accept on positive
decision or with Access-Reject otherwise. If the decision require additional information exchange, Access-Challenge
is sent to the NAS.

In case if NAS is configured to send the connection info, after establishing a connection UTM5 RADIUS sends an
Accounting-Request. Depending on the configuration, NAS may also send additional periodical Accounting-Requests
containing current status info on the connection.
When a connection is broken, NAS must send a summarizing Accounting-Request, given that some
Accounting-Requests for this connection have already been exchanged before.
On receiving an Accounting-Request, UTM5 RADIUS creates, changes, or removes an object associated with the
given connection. Depending on the Accounting-Request contents, some additional actions may be performed to
maintain the delivered information on the connection.
After successfully handled an Accounting-Request, UTM5 RADIUS sends to NAS a confirmation
Accounting-Response. On failure, no response is sent. Packets from an unknown (not registered) NAS are ignored.
The interaction between UTM5 RADIUS and NAS is performed in RADIUS packets sent over UDP. Commonly, port
1812 is used by UTM5 RADIUS to receive Access-Requests, and port 1813 to receive Accounting-Requests.


119
RADIUS protocol description 

Generally a RADIUS packet contains the following fields:

Packet fields description:

– Code – is an one-byte field used to identify the RADIUS packet type. UTM5 RADIUS supports the following types:

Type Name Sent or received by UTM5 RADIUS

1 Access-Request Received
2 Access-Accept Sent
3 Access-Reject Sent
4 Accounting-Request Received
5 Accounting-Response Sent
11 Access-Challenge Sent

– Identifier – is a one-byte field intended to relate the request to the response. Duplicate requests with the same ID
coming from the same NAS shortly after each other are ignored.
– Length – is a two-bytes field containing packet size.
– Authenticator is a 16-bytes field that contains data for checking the packet's authenticity. – For a request, it
is some unique sequence used together with the md5 of the secret word common for the UTM5 RADIUS and NAS
for reversible encoding of the user’s password. For a response, it is md5 of Code, Identifier, Length,
Authenticator, and Attributes fields together with the secret word.
The common secret word must be considerably hard to break. It is strongly not recommended to leave it blank.
UTM5 RADIUS uses the sender address of the RADIUS packet to derive the common secret word.
– Attributes – is a variable-length field containing the list of RADIUS attributes.

Starting from version 5.3-004 UTM5 supports tagged RADIUS attributes

Each RADIUS attribute contains specific information on a request or a response. Generally, a RADIUS attribute looks

as follows:
– Type – is a number describing the attribute type.
Possible types are listed in RFC 1700.
http://www.iana.org/assignments/radius-types/radius-types.xhtml#radius-types-2
– Length – is the summary length of the Type, Length, and Value fields.
– Value – is the type-specific information. Depending on the type, may contain the following fields:


120
RADIUS protocol description 

– text – from 1 to 253 bytes of UTF-8 text, zero byte forbidden;

– string – from 1 to 253 bytes of binary info;
– address – is a 32-bit data interpreted as an address;
– integer – is a 32-bit data interpreted as unsigned integer;
– time – is a 32-bit data interpreted as time in seconds since 00:00:00, January 1, 1970 UTC.
Some of the attributes may be included in a packet more than once. In this case their interpretation depends on the
attribute type. Order of attributes is important.
Additional attributes set in NAS, services and service links settings are also included in the packet. Attributes set in NAS
settings are added first, then go the attributes from the services settings and then the attributes from the service link
settings. UTM5 allows one to perform certain actions when adding an attribute like replace or remove an attribute added
earlier. That is, the attributes from service link settings have the highest priority. For more details see Additional
RADIUS attributes on page 71
From this point on, the RADIUS attributes are referred by common name followed by the typeID in parentheses, for
example: User-Name (1).
There is a certain attribute type Vendor-specific (26) designed to store extended vendor-specific data. These data are

interpreted as follows:
– Vendor-Id – is a number describing the organization that defines this attribute (for more details see RFC 1700).
– Vendor-Type – is a number that described the attribute meaning.
– Vendor-Length – is the summary length of the Vendor-Type, Vendor-Length and Data fields.
– Data – contains the actual data.
From this point on, the vendor-specific attributes are referred by common name followed by the semicolon-separated
Vendor-Id and Vendor-Type in parentheses, for example: Cisco-AVPair (9;1).

DM and CoA requests

When session parameters need to be changed or a session needs to be terminated, UTM5 RADIUS may send CoA
(Change-of-Authorization) or DM (disconnect-message) requests according to RFC 5176. UTM5 sends a separate
request for each session for changing parameters or terminating a session.
DM and CoA requests have the same format and are send to the 3799 UDP port. This port may be changed in NAS
settings (see Administrator’s interface: NAS list on page 70).
DM requests are used to terminate session if user’s account balance becomes negative. The following attributes might
be used to identify a session:
– User-Name – is a user name, associated with one or more sessions
– NAS-Port – is a port used by session that needs to be terminated
– Framed-IP-Address – is an IPv4 address associated with the session
– Vendor-Specific – is one or more vendor-specific attributes
– Called-Station-Id – is the called party identifier
– Calling-Station-Id – is the calling party identifier
– Acct-Session-Id – is an ID that let’s one clearly identify a session on a NAS


121
Workflow description 

NAS replies with a Disconnect-ACK in case it was able to identify and terminate the session, otherwise it replies with
a Disconnect-NAK.
CoA requests are used for changing shaping parameters for current session (for more information see UTM5
Dynashape: Workflow description on page 148). These parameters are most likely to be changed at a certain time
or after reaching a certain traffic limit. In case NAS supports CoA requests and a corresponding flag is checked in the
administrator’s interface, if one of these happens, UTM5 RADIUS will send a CoA request to NAS.
Like a DM request, CoA request contains attributes required for identifying a session and the new values of RADIUS
parameters that need to be updated (see UTM5 Dynashape: RADIUS parameters on page 149). If NAS is able to
identify session and update RADIUS parameters it replies with a CoA-ACK, otherwise it replies with a CoA-NAK.

Workflow description
RADIUS works as follows:
1. Connects to the UTM5 core.
2. Retrieves from UTM5 the info on events to await.
3. Interacts with NAS.
4. Sends the resulting data to UTM5.

On startup UTM5 RADIUS connects to the UTM5 core, authorizes according to its config file parameters, and
establishes a Stream connection.
Once a connection is set, the UTM5 core passes to UTM5 RADIUS the description of the needed objects in the
corresponding events.
UTM5 RADIUS keeps the Stream connection to the core. Upon creating, changing, or deleting system objects related
to UTM5 RADIUS functionality, the UTM5 core sends the corresponding event over Stream in order to inform RADIUS.
On reception of certain events, UTM5 RADIUS creates, modifies or deletes its inner records related to the following
objects:
– IP groups;
– NAS;
– Accounts;
– Time ranges;
– IP traffic, hotspot, and telephony services;


122
Workflow description 

– IP traffic, hotspot, and telephony service links;

– Telephone zones;
– Telephone directions;
– IP pools.

Authorization
On receiving an Access-Request UTM5 RADIUS performs the following:
1. User authentication with one of the methods:
– PAP
– CHAP
– MS-CHAP v1
– MS-CHAP v2
– EAP-MD5
– EAP-TTLS
– Digest

The Digest authentication is implemented according to http://tools.ietf.org/id/draft-sterman-aaa-sip-00.txt,

rather than the corresponding RFC.

The authorization request must contain the User-Name (1) attribute. The portion of its value before ':’ is
interpreted as the Callback_prefix parameter and the rest proceeds to the next step and is interpreted as a login.
All letters contained in the login are cast to lower case. If the User-Name (1) attribute is missing, the
Access-Request is ignored and the rest of actions skipped.
If authentication fails or requires unsupported method, an Access-Reject is sent to NAS.
If the guest_pool_name parameter is set in the UTM5 RADIUS config file (see Configuration file on
page 127), the guest users may be authorized as well.
1. Using the login from step, a corresponding service link is found. The following actions depend on the service link
type.
– For an IP traffic service link:
* If the radius_auth_vap parameter is set in the UTM5 RADIUS config file, the account referred in the given
service link is checked for blocking.
* The given IP group is checked for presence of free IP addresses.
* If the IP group parameter Allowed CID is not empty, the Calling-Station-Id (31) value is checked against it as
a regular expression.
* If the radius_nas_port_vpn parameter is set in the UTM5 RADIUS config file, the NAS-Port-Type (61)
value is checked to match one of its values.
Failure of any of these checks result in sending an Access-Reject packet and skipping the rest of actions.
If the checks are successful, an Access-Accept packet is sent with the following attributes:
* Service-Type (6) set to 2.
* Framed-IP-Netmask (9) set to 0xFFFF FFFF.
* Framed-Routing (10) set to 0.
* Framed-Protocol (7) set to 1.
* Framed-IP-Address (8) set to the first free IP address in the given IP group. The IP address is marked busy
for the time span defined by the parameter radius_ippool_acct_timeout from the UTM5 RADIUS
config file.


123
Workflow description 

* Session-Timeout (27) set to the value of radius_default_session_ timeout parameter from the UTM5
RADIUS config file.
– For a dial-up service link:
* The Callback_prefix parameter is checked for consistency with the Callback allowed and Ringdown
allowed parameters. That is, if Callback allowed is not set, Callback_prefix must not be set. On the
contrary if Ringdown allowed is not set, Callback_prefix must be set.
* If Allowed CID is not empty, the Calling-Station-Id (31) value is checked against it as a regular expression.
* If Allowed CSID is not empty, the Called-Station-Id (30) value is checked against it as a regular expression.
* The amount of connections established for this service link is compared to the maximum number of
simultaneous connections set in the service properties.
* If the blocked_pool_name parameter is not set in the UTM5 RADIUS config file, the given account is
checked for blocking.
* Maximum connection time is calculated from the account balance and the service link parameters. The check
will sucessfully pas if the max connection time is greater than 0 and the current time is in the set bounds and
if the current account balance is enough for at least one second of connection.
* If a registered IP pool is set in the service properties, it is checked for presence of free addresses. If there are
no free addresses, the check won't pass.
* If the radius_nas_port_vpn parameter is set in the UTM5 RADIUS config file, the NAS-Port-Type (61)
value is checked to match one of its values.
Failure of any of these checks result in sending an Access-Reject packet and skipping the rest of actions.
If the checks are successful, an Access-Accept packet is sent.
the user is blocked and the blocked_pool_name parameter is set in the UTM5 RADIUS config file, the IP
address will be issued from the pool intended for blocked users, which is defined by this parameter.

When user’s account is unblocked, a DM (disconnect message) will be sent in order to break the session. After
that, the customer will require to reconnect

If the user is not registered and the guest_pool_name parameter is set in the UTM5 RADIUS config file, the IP
address will be issued from the pool intended for guest users, which is defined by the guest_pool_name
parameter.
If the dial-up service parameter Pool name is set to some registered IP pool, the following attributes are
returned:
* Service-Type (6) set to 2.
* Framed-IP-Netmask (9) set to 0xFFFF FFFF.
* Framed-Routing (10) set to 0.
* Framed-Protocol (7) set to 1.
* Framed-IP-Address (8) set to the free IP address from the given IP group. The IP address is marked busy for
the time span defined by the parameter radius_ippool_acct_timeout from the UTM5 RADIUS config
file.
* Session-Timeout (27) set to the maximum session time.
If the dial-up service parameter Pool name is set to some registered IP pool, the following attributes are
returned:
* Service-Type (6) set to 2.
* Framed-MTU (12) set to 1500.
* Framed-Routing (10) set to 0.
* Framed-Protocol (7) set to 1.
* Session-Timeout (27) set to the maximum session time.


124
Workflow description 

* Cisco-AVPair (9;1) set to addr-pool=<pool name>.

Besides that, if Callback_prefix is set, the following attributes are added:
* Callback-Number (19) set to callback number, if the UTM5 RADIUS config file parameter
radius_callback_avpair_enable is not set.
* Callback-Id (20) set to Callback login, if the RADIUS config file parameter
radius_callback_avpair_enable is not set.
* Cisco-AVPair (9;1) set to lcp:callback-dialstring=<callback_ -prefix>, if
radius_callback_avpair_enable is set.
The issued IP address is marked busy for the time span defined by the parameter radius_ippool_timeout
from the UTM5 RADIUS config file.
– For a telephony service link: see IP telephony module: Workflow description on page 192.
For any type of service, the NAS attributes set for the service link are included in the Access-Accept response.

Accounting
Accounting-Requests are used by UTM5 RADIUS to determine if an IP address is occupied, charge for hotspot, dial-up
or telephony services, charge for consumed traffic and dynamically create, modify or remove IP groups.
Accounting-Request must contain the following attributes:
– Acct-Status-Type (40)
– Acct-Session-Id (44)
– Framed-IP-Address (8)
If any of these attributes is missing, the request is ignored.
Type of the request is defined by the Acct-Status-Type (40) attribute.
UTM5 The following request types are recognized by RADIUS:

Attribute value Acct-Status-Type Name Comment

1 Start Session start
2 Stop Session end
3 Interim-Update Intermediate data related to the established
connection

– On receiving a Start packet:

– An object describing the session is created and the core is informed over Stream. The Acct-Session-Id (44)
parameter contains the object ID.
– If the login set in User-Name (1) belongs to some IP group or a dial-up service link, the last IP address of this IP
group or a service link is marked busy for the time span defined by radius_ippool_timeout, if this parameter
is set, or for three times as long as interim_update_interval, if this parameter is set (the former having
higher priority).
– IP address associated with the session is marked busy.
– On receiving a Stop packet:
– If the login set in User-Name (1) corresponds to some IP traffic or hotspot service link, the session is tariffed based
on the time set in Acct-Session-Time (46). The information about a needed charge is sent to the core via Stream
protocol in a corresponding event.
– The object that describes session is removed. The information about this object deletion is sent to the core via
Stream protocol in a corresponding event.
– IP address is marked as unused.
– On receiving an Interim-Update packet:


125
Session control mechanism 

– The object that describes session is modified.

– If the login set in User-Name (1) belong to some dial-up service link, and the Interim-Update session control is on,
the IP address of the given service link is marked busy for three times as long as interim_update_interval, if this
parameter is set.
There are certain properties of RADIUS requests processing.
For an incoming Stop or Interim-Update requests with a session ID that doesn’t match any open session ID, a new
session will be created. The UTM5 RADIUS module may cache the list of closed sessions to avoid creating new
sessions when receiving a Stop or an Interim-Update requests for an already closed session. This feature is turned off
by default. In order to employ a closed sessions cache, one has to change the following parameters of the configuration
file:
– use_closed_sessions_cache=on
– closed_sessions_cache_size=<number> is the cache size (the number of closed sessions to store
information of).
When the closed sessions cache is employed, if a session status changes to closed, it’s Acct-Session-Id is added to
the cache. On receiving Stop or Interim-Update request, the system will first check the cache. If the Acct-Session-Id
fount in the request is present in the cache, this request won’t pass to UTM5 core. When receiving a Start request, the
corresponding Acct-Session-Id is removed from the cache.

When the number of entries reaches the cache size limit, the oldest entry is removed and the new one is added.
The larger the cache the less the probability of creation of a new session for a Stop or Interim-Update request.
But at the same time searching requires more resources.
For each system the cache size depends on many parameters such as the number of registered users, the
number of allowed sessions for a single user, etc. That is why the closed_sessions_cache_size parameter
doesn’t have a default value.

When RADIUS server stops, all the information about closed sessions is lost.

Tariffication by Stop packets

If the access server does not support the export of statistics by NetFlow, an option of tariffication by Stop packets may
be used. For that the radius_do_accounting parameter must be set to 1.
On receiving the Stop packet, the RADIUS server creates two traffic records which later on are accounted in a standard
way.
The first record contains the access server IP address for sender address, the subscriber IP address for destination
and the Acct-Input-Octets (42) value from the Stop packet for the traffic amount consumed. The second record contains
the NAS IP address for destination, the subscriber IP address for source, and the Acct-Output-Octets (43) value for the
traffic amount.
The created records are sent to the UTM5 core over Stream.

Session control mechanism

If the interim_update_interval parameter (see Configuration file on page 127) is set, it is implied that the NAS
sends Interim-Update packets periodically with this interval. When a packet does not arrive within three intervals, or
when a Stop packet arrives, the session is dropped and the corresponding IP addresses released.
By default this parameter is not set, so the session may be dropped only upon arrival of Stop packets. If the NAS
supports sending the Interim-Update packets, it is better to set this parameter to some reasonable value in order to
avoid the occurrence of “hanging” sessions.


126
utm5_radius daemon 

utm5_radius daemon
The UTM5 RADIUS executable file is called /netup/utm5/bin/utm5_radius.
Possible command line parameters are:

-p <path> Path to the PID file

-c <path> Path to the config file
-V Version number and parameters information

The following options for utm5_radius startup are available:

1. Direct start of the utm5_radius executable with necessary parameters;
2. Start on watchdog with start parameter:

/netup/utm5/bin/safe_utm5_radius start

The script will restart utm5_radius automatically on failure;

1. Start via the automatic startup script (recommended).
On Linux:

/etc/init.d/utm5_radius start

on FreeBSD or Solaris –

/usr/local/etc/rc.d/utm5_radius.sh start

This will launch the watchdog script.

To stop the utm5_radius and the watchdog script, execute:
on Linux –

/etc/init.d/utm5_radius stop

on FreeBSD or Solaris –

/usr/local/etc/rc.d/utm5_radius.sh stop

Core settings
UTM5 RADIUS server should be installed to /netup/utm5/bin/utm5_radius. Its parameters may be set up in the
following ways:
– Via the config file;
– Via the administrator’s interface (see System core: Settings available in the administrator’s interface on
page 117for more detail).
Config file parameters are used during the initialization of the UTM5 RADIUS module.

Configuration file
UTM5 RADIUS server running uses /netup/utm5/radius5.cfg as its config file.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.


127
Core settings 

The list of the possible parameters:

Parameter Possible Default value Description

values
core_host IP address Mandatory Address of UTM5 core host.
parameter
core_port 1 – 65534 Mandatory Address of UTM5 core port listenst to Stream
parameter messages (parameter stream_bind_port
of the core configuration file).
radius_login string radius RADIUS server system user login used to
connect to UTM5 core.
radius_password string radius System user password for UTM5 core access.
radius_pid_file file name /var/run/ PID file.
utm5_radius.pid
radius_ping_interva number 30 Maximum duration (in seconds) of repeated
l attempts to connect to the core
radius_acct_host IP address 0.0.0.0 Host to accept Accounting-Request
radius_acct_port 1 – 65534 1813 Port to accept Accounting-Request
radius_auth_host IP address 0.0.0.0 Host to accept Access-Request
radius_auth_port 1 – 65534 1812 Port to accept Access-Request
radius_auth_mppe enable not set Enables 128 bit MPPE on authorization via
MS-CHAP-v2 protocol
radius_auth_vap 1 not set If set, disables authorization of blocked users
radius_ippool_acct_ time in seconds 30 Time in seconds for blocking IP addresses in
timeout the pool after sending Access-Accept packet
radius_ippool_timeo time in seconds not set Time in seconds for blocking IP addresses in
ut the pool after accepting the Accounting-Start
packet. We do NOT recommend using this
parameter
radius_auth_null yes or enable not set If enabled, RADIUS server will accept and
successfully authorize the requests without
passwords when the user password is empty
radius_auth_h323_re enable, on, yes not set If enabled, the authorization is performed by
mote_address Cisco VSA h323-remote-address attribute
rather than by username attribute
radius_nas_port_vpn Integer not set (no If set, the NAS-Port-Type (61) attribute is
a. Multiple instances of the checking) checked against this value on authorization of
parameter are possible. the IP traffic user
radius_nas_port_dia Integer not set (no If set, the NAS-Port-Type (61) attribute is
lup (a) checking) checked against this value on authorization of
the dial-up user
radius_nas_port_tel Integer not set (no If set, the NAS-Port-Type (61) attribute is
(a) checking) checked against this value on authorization of
the telephony user
radius_nas_port_hot Integer not set (no If set, the NAS-Port-Type (61) attribute is
spot (a) checking) checked against this value on authorization of
the hotspot user


128
Core settings 

Parameter Possible Default value Description

values
radius_card_-autoad yes, on, enable not set (no Enables automatic registration of card users
d registration) (card number and PIN stand for login and
password, correspondingly). User should fill
the Login field with the card number, and the
Password field with the card's PIN code. In
case of telephony service, PIN code or it's part
is used as a login and the rest of it is used as
a password.
send_xpgk_ep_number any not set (numbers Enables sending the Cisco-AVPair (9;1)
not sent) attribute having value xpgk-ep-n-umber=<
semicolon-separated list of numbers > in the
Access-Accept request for telephony users
send_h323_ivr_in any not set (numbers Enables sending the Cisco-AVPair (9;1)
not sent) attribute having value
h323-ivr-in=terminal-alias: <
semicolon-separated list of numbers > in the
Access-Accept request for telephony users
h323_origin_-reject string not set Sets zero cost for Accounting-Request having
the h323-call-origin (9;26) attribute equal to
this parameter’s value
interim_update_inte time in seconds > not set (standard Enables advanced session control
rval 60 mechanism used) mechanism based on Interim-U-pdate
packets. The value is passed via the
Acct-Interim-In-terval (85) attribute of the
Access-Accept packet
radius_default_sess Integer 86400 Value of the Session-Timeout (27) attribute
ion_timeout sent in Access-Accept for an IP traffic service
radius_callback_avp any not set Enables sending of the Cisco-AVPair (9;1)
air_enable attribute having value
lcp:callback-dialstring=<
callback n-umber >, where callback
number is a part of login preceding the colon
symbol
radius_acct_rewrite enable, on, true not set Enables substitution of login with the
_login_answer h323-remote-address (9;23) attribute value
for the Accounting-Request packets having
the h323-call-origin (9;26) attribute set to
answer
radius_acct_rewrite enable, on, true not set Enables substitution of login with the
_login_originate h323-remote-address (9;23) attribute value
for the Accounting-Request packets having
the h323-call-origin (9;26) attribute set to
originate
blocked_pool_name string not set Name of the IP pool to provide addresses for
blocked users (in case those are entitled to
some limited Internet access)
guest_pool_name string not set Name of the IP pool to provide addresses for
guest users (in case those are entitled to
some limited Internet access)


129
Core settings 

Parameter Possible Default value Description

values
named_pool_shuffle yes, no not set Enables providing IP addresses from a
random pool (if there are several with similar
name). By default the addresses are issued
from each pool in turn until it runs out; the
pools follow in the order of addition
radius_auth_tel_ext yes, on, enable not set Enables recognizing of registration request by
_reg the condition Calling-Station-Id =
Called-Station-Id in Access-Request
tls_certificate_pat string not set Path to the certificate file when using
h EAP-TTLS
tls_private_key_pat string not set Path to the private key file when using
h EAP-TTLS
tel_session_timeout Integer 86400 Maximum duration (in seconds) of a VoIP
session
disconnect_re- Integer 5 PoD response timeout after manual drop of
quest_timeout the session
any not set Incoming trunk format:
incoming_trunk_for- Vendor_id:attribute_id:regexpoutgoing_trunk
mat
_formatanynot
any not set Outgoing trunk format:
outgoing_trunk_for-
mat Vendor_id:attribute_id:regexppbx_id_formata
nynot
any not set Call id format:
pbx_id_format Vendor_id:attribute_id:regexpoverride_servic
e_typetrue,
override_service_- true, false false Override service type in the incoming request.
type Set service type “framed”
IP address 0.0.0.0 Host to accept requests for connection
dac_bind_host parameters modification (incoming RADIUS
server request)
string USD Currency code. Is used by IP telephony
h323_currency
module
use_closed_ses- yes, on, enable not set Store information about recently closed
sions_cache sessions in cache
closed_ses- integer 0 Closed sessions cache size in number of
sions_сache_size sessions stored
yes, on, enable not set Make RADIUS server return
h323_re-
turn_code_positive Cisco:h323_return_code attributes with
positive values.

Logging parameters (for more details see System description: Logging on page 13):

Parameter Possible Default value Description

values
log_level number from 0 to 1 Level of messages to be written to the log file
3
log_file_main file name standard error Main log file
stream


130
Dynamic IP address allocation 

Parameter Possible Default value Description

values
log_file_debug file name standard error Debugging log file
stream
log_file_critical имя файла standard error Critical log file
stream
rotate_logs yes, on, enable not set (rotation Enables log files rotation
off)
max_logfile_size size in bytes 10485760 Maximum size of a log file
a. Relevant if log files rotation
is enabled.

b. Interface parameters

string not set A prefix added to log file names when the
syslog_name
syslog recording is enabled

Dynamic IP address allocation

To enable tariffication of traffic in case of the dynamically assigned user’s IP addresses, a scheme of dynamic
connection of IP address to service link is introduced.
The IP traffic service or dial-up/hotspot service link bound to the user’s account must have its Dynamic IP addresses
option switched on.
On receiving the Accounting-Start request having login of the user in question for the User-Name (1) attribute and
non-zero IP address for Framed-IP-Address (8), the UTM5 core sends an event to link this IP address to the account.
The event contains the account details and the issued IP address. The event handler calls the function that performs
all the necessary validations and the linking itself (if applicable).
Control flow of the said function goes as follows:
1. Search for the IP traffic service link having its Dynamic IP addresses option on and bound to the given account. If
not found, skip the rest;
2. Search for the IP group to which the given IP address belongs. If found, remove the group;
3. Create an IP group with the given IP for address and 255.255.255.255 for mask (leave default values for the rest of
parameters); Other IP group parameters are assigned default values;
4. The IP group is connected to the service link found on step 1.
When creating or removing IP group, the system performs the following actions: If the Internet for the personal account
that the IP group belongs to is On,
– It changes to Off before creating or removing an IP group;
– After the IP group has been created or deleted the Internet status changes back to On.
Besides that a couple of Internet access enable events might be generated for the personal account if the Internet
status was Off.
We do NOT recommended using dynamic IP address allocation if the address pool overlaps with the static IP
addresses that are already associated with IP traffic service links.


131
Introduction 

Text files import 12

Introduction
NetUP UTM5 supports importing text files containing the data on traffic and phone calls. Some other entities may also
be imported, albeit in a different way.
For importing traffic subclasses from CSV files, see Administrator’s interface: Traffic classes on page 43.
For importing structured information related to some complex objects from XML files, see Structured data import on
page 158.
utm5_send_traffic should be employed to import traffic info in case if the said info contains neither sender nor
destination address, but provides the data on traffic quantity, its class, and the login of the IP traffic service link to which
the traffic belongs. If the option of providing traffic data via NetFlow is available, it should be used instead.
utm5_send_cdr should be used to import the info on phone calls in case if the provider of the said info does not
support the RADIUS Accounting-Request. If the option of sending the phone calls info via the RADIUS
Accounting-Requests is available, it should be used instead.

Prior to the version UTM5.3-001 both these tasks were performed by a single application called UTM5 Unif. Input
files format and most of the config file parameters are retained fully compatible with those of UTM5 Unif.

Workflow description

Parsing traffic info files

In case of parsing a traffic info file the following actions are performed:
1. A connection is established to the UTM5 core using URFA protocol.
2. The file is read line by line, and each line parsed according to standard format.
3. Data from each string are stored in the internal format.
4. Data structures in the internal format are passed to UTM5 by calling the URFA function 0x5511.
5. utm5_send_traffic stops.
The traffic data file should contain the data in the following format:
1. Each string must be formatted like: 

<LOGIN> <BYTES> <TCLASS> <IP>

where
– LOGIN – is the login of the IP traffic service link to which the traffic belongs;
– BYTES – is the traffic amount in bytes (should not exceed 2GB);
– TCLASS – is the number of traffic class registered in UTM5 to which this traffic belongs;
– IP – is an IP address specified for this traffic in traffic reports grouped by IP. May contain arbitrary value.
2. The file should contain neither strings containing any other information, nor information in a different format.

Parsing phone call info files

In case of parsing a phone calls info file the following actions are performed:
1. A connection is established to the UTM5 core using URFA protocol.
2. The file is read line by line, and each line parsed according to standard format.
3. Data from each string are stored in the internal format.


132
Utilities usage 

4. Data structures in the internal format are passed to UTM5 by calling the URFA function 0x10310.
5. utm5_send_cdr stops.
The phone calls data file should contain the data in the following format:
1. Each record of a phone call must be on a separate line.
2. No record may span more than one line.
3. Each record must conform to the format specified in the config file. The format should conform the common
telephony call record requirements.
4. The file should contain neither strings containing any other information, nor information in a different format.
Each single record must meet the following requirements:
1. To contain text data on one call.
2. To contain several fields: The following fields are mandatory:
– Calling party ID (telephone number);
– Called party ID (telephone number);
– Call length in seconds;
– Call date and time, if the call is going to be recorded under date different from current;
The following optional fields may also appear:
– Incoming trunk;
– Outgoing trunk;
– PBX ID;
– Unique call ID (optional).
If the call date format is not specified in the config file, the following is assumed by default:

<hh>:<mm>:<ss>.<mil> <tzc> <dow> <mon> <dt> <yyyy>

Field Length Description

hh 2 Hours
mm 2 Minutes
ss 2 Seconds
mil 3 milliseconds
tzc 3 Time zone code
dow 3 Day of week
mon 3 Month
dt 2 Date
yyyy 4 Year

For example, 00:35:05.000 UTC Tue Jul 19 2007.

Milliseconds and day of week are ignored.
The field delimiter symbol is also specified in the config file and must be the same along the whole data file.

Utilities usage
The utilities are started as follows:

/netup/utm5/bin/utm5_send_traffic


133
Utilities usage 

and

/netup/utm5/bin/utm5_send_cdr

The acceptable command line parameters for both utilities are:

-c <file> Path to the config file

-s <file> Path to the data file to be imported. “ - ” denotes STDIN.
By default, /netup/utm5/source.dat is used
-v Version number and parameters information

Config files
The utilities use config files utm5_send_traffic.cfg and utm5_send_cdr.cfg, which on Unix platforms are
located at /net-up/utm5/. In Win32 version they are placed into the installation directory (which by default is
C:\Program Files\NetUP\UTM5\).
Config files have the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
Below is the list of possible parameters.
Parameters of connection to the UTM5 core (present in both files):

Parameter Possible Default value Description

values
core_host IP address 127.0.0.1 IP address of the UTM5 core.
core_port 1 to 65534 11758 Port of the UTM5 core that listens to URFA
(urfa_bind_port parameter in the core
configuration file).
core_login string init System user login for UTM5 core access.
core_password string init System user password for UTM5 core access.

Parameters for parsing phone call info files (found only in utm5_send_cdr.cfg):

Parameter Possible Default value Description

values
pbx_calling_sid Integer 0 Number of position containing the calling
number
pbx_called_sid Integer 1 Number of position containing the called
number
pbx_duration Integer 2 Number of position containing the call duration
pbx_duration_forma format string default format Call duration format (a).
t
pbx_session_id Integer 3 Number of position containing the session ID
pbx_date_time Integer 4 Number of position containing the date and
time of the call
pbx_date_format format string default format Date and time format (a).


134
Utilities usage 

Parameter Possible Default value Description

values
pbx_time Integer not set Number of position containing the time of the
call (if stored separately from
date)pbx_time_f-ormatformat string not
setTime format).
pbx_time_format format string not set Call start time format (a).
pbx_accounting_cod Integer not set Number of position containing the username (if
e it is included)
pbx_incoming_trunk Integer not set Number of position containing the incoming
trunk (if present)
pbx_outgoing_trunk Integer not set Number of position containing the outgoing
trunk (if present)
pbx_id Integer not set Number of position containing the PBX ID (if
present)
pbx_delimiter string space Field delimiter symbol
pbx_quote string empty string Field enclosing symbol

a. Time format string may include specifiers %H, %h, %M, %m, %S, and %s, see below.

Date format string may include specifiers, see the full list below.

SpecifierDescrip
tion
%Y Four-digit year (1970...)
%y Two-digit year (00..99)
%N Month with leading zeros (01..12)
%n Month without leading zeros (1..12)
%H Hour with leading zeros (00..23)
%h Hour without leading zeros (0..23)
%D Day of the month with leading zeros (01..31)
%d Day of the month without leading zeros (1..31)
%M Minutes with leading zeros (00..59)
%m Minutes without leading zeros (0..59)
%S Seconds with leading zeros (00..60)
%s Seconds without leading zeros (0..60)
%b Three-letter month name (Jan..Dec)
%U Time in unix timestamp format
%z Time zone identifier (for example, GMT) – valid only for FreeBSD
and Linux
% any symbol


135
Utilities usage 

Logging parameters (for more details see System description: Logging on page 13):

ParameterPossible
valuesDefault
valueDescription
log_level number from 0 to 1 Level of messages to be written to the log file
3 (unless -d option is set)
log_file_main file name standard error Main log file
stream
log_file_debug file name standard error Debugging log file
stream
log_file_critical file name standard error Critical log file
stream


136
UTM5 RFW workflow 

UTM5 RFW 13
UTM5 RFW workflow
RFW is a daemon that executes the commands issued by the UTM5 core. RFW is intended for controlling the external
software, including firewalls, routers, shapers, etc.
RADIUS works as follows:
1. Connect to the UTM5 core;
2. Receive commands from UTM5;
3. Execute commands locally or remotely.
On startup UTM5 RFW authorizes in the system using the parameters given in its config file. For successful
authorization UTM5 RFW must be registered in the list of firewalls (see Administrator’s interface: Firewalls on
page 69). The amount of UTM5 RFWs in the system is unlimited.
UTM5 RFW establishes permanent connection with the UTM5 core using the Stream protocol and awaits for
commands issued by the core on some events. Commands for particular events are assigned in the administrator’s
interface on Settings: Firewall rules page.

The commands are executed either on the same server where RFW is running (if the firewall type is set to Local), either
remotely over rsh, if it was set to Remote Cisco.
If the RFW is not connected to the core, the commands are cached for 24 hours. On reconnection of RFW to the core
some commands may be executed according to the given synchronization parameters (see Synchronization of rules
on page 147); if the reconnection was without any flags, all cached rules will be sent to the affector. Also, an arbitrary
command may be assigned for execution on RFW startup by the firewall_flush_cmd parameter (see
Configuration file on page 145).


137
Firewall rules 

Firewall rules
A firewall rule is an object that contains the command’s template and defines the conditions to execute the command.
The set of registered firewall rules may be found at Settings: Firewall rules page of the administrator’s interface.
Firewall rules ready for execution are passed to the UTM5 RFW.
Firewall rules have the following parameters:
– Applicability domain (to which users it is applicable);
– Initiating event (the event that causes the rule to execute);
– Place to apply (RFW to which the rule is passed and the corresponding firewall where it is actually executed);
– Template (the command proper).
The command templates may include variables which are substituted with their values on sending the command to
RFW.
– Applicability domain – is a property that defines accounts to which the rule is applicable. If All users option is
checked, the rule is applicable to all accounts in the system. Otherwise the subset of interest may be defined by
user ID, by group, or by the tariff plan. Several conditions may be used simultaneously, combined by default with
logical OR, though an alternative option of using logical AND is also available.

Selection by tariff plan covers the accounts having (among others) some tariff links with this tariff plan set as
current. The rules applicable to service links or IP groups will be applied to all service links or IP groups related
to these accounts, including those which by themselves are connected with different tariff plans.

– Initiating event – (one or more) is the event to trigger command execution is selected from the list (see Events on
page 143).
– Place to apply – selects the firewall to use from the list of existing firewalls, or probably selects all of them.
– Command template – is a string probably containing variables (see Variables) which are substituted with their
values on sending the command to the RFW.
When executing locally, an RFW calls the command as follows:

[sudo_path ][firewall_path ]arg1[ arg2[ arg3...]]

Here the optional parameters sudo_path and firewall_path are taken from the config file, and the rest is the
command template where variables are already substituted with their values. Therefore the case when neither
sudo_path nor firewall_path is set requires the command template to start with the name of some external
executable file.

In UTM5 assembled for Win32 the sudo_path and firewall_path parameters are not used.

When executed over rsh, the command is sent as is, i.e. just the template with substituted variable values.
An example of firewall rules creation is described in Creating firewall rules on page 110.

Rules created in versions prior to 5.2.1-007 must be converted (see Rules conversion on page 144).

Variables
Below is the list of all variables that may be used in command templates, together with their scope (i.e. the events to
which every particular variable is applicable). If the variables are used outside of their scope, they are substituted with
their default values.


138
Firewall rules 

Find the list of events below (see Events on page 143)

Variable Default value Scope Description

UID empty string All events excluding User ID
closing detailed
UGROUP empty string Semicolon-delimited list of IDs of groups which
statistics file and the
the user belongs to
logfile
LOGIN empty string User login
EMAIL empty string All events excluding E-mail address set in the user’s properties
closing detailed
ACCOUNT_ID 0 Account ID
statistics file, closing
RULE_ID 0 logfile and User User ID plus fw_rule_ offset value from the
deleted list of system parameters.
FULL_NAME empty string Full name of a user
MOBILE_PHONE empty string User mobile phone number
WORK_PHONE empty string User work phone number
HOME_PHONE empty string User home phone number
SWITCH_IP empty string Firewall name set in the Remote switch field in
the user properties (see : Other on page 35)
SWITCH_PORT empty string Port set in the user’s properties (see : Other on
page 35)
SLINK_ID 0 All events excluding Service link ID
closing detailed
statistics file, closing
logfile, Add user, Edit
user and Balance
events
ULOGIN empty string Internet events  Login set in the properties of a service link or an IP
Add/Edit/Delete group
dialup service link, 
hotspot enabled,
hotspot disabled, Set
bandwidth limit
(incoming), Edit
bandwidth limit
(incoming), Delete
bandwidth limit
(incoming), Set
bandwidth limit
(outgoing), Edit
bandwidth limit
(outgoing) and Delete
bandwidth limit
(outgoing)


139
Firewall rules 

Variable Default value Scope Description

UIP 0.0.0.0 Internet events, User network address set in the IP group
hotspot enabled, properties under IP.
hotspot disabled, Set
UMASK 255.255. Dot-separated network mask (for example,
bandwidth limit
255.255 255.255.255.0)
(incoming), Edit
UINVERTMASK 0.0.0.0 bandwidth limit Dot-separated inverted network mask (for
(incoming), Delete example, 0.255.255.255). Used for Cisco routers.
UBITS 32 bandwidth limit Binary network mask (for example, 
(incoming), Set 32 means 255.255.255.255).
bandwidth limit
(outgoing), Edit
bandwidth limit
(outgoing) and Delete
bandwidth limit
(outgoing)
MAC empty string Internet events, Set MAC address set in the IP group properties.
bandwidth limit
(incoming), Edit
bandwidth limit
(incoming), Delete
bandwidth limit
(incoming), Set
bandwidth limit
(outgoing), Edit
bandwidth limit
(outgoing) and Delete
bandwidth limit
(outgoing)
SERVICE_ID 0 Add/ Edit/Delete Service ID
dialup service link,
Open session, Close
session,
Add/Edit/Delete IP
traffic service link,
Add/Edit/Delete
telephony service
link, Add/Edit/Delete
tech parameter
Add/Edit/Delete IPTV
service link
UPASS Empty string Add/Edit/Delete hotspot or dialup service password.
dialup service link,
hotspot enabled and
hotspot disabled
DIALUP_FLAGS empty string Add/Edit/Delete Dialup service link flags:
dialup service link 0 – Ringdown allowed is set; 
3 – Callback allowed is set; 
1 – both are set
UCID empty string CID parameter value for a dial-up service link
UCSID empty string CSID parameter value for a dial-up service link


140
Firewall rules 

Variable Default value Scope Description

DIALUP_LIST empty string Blocking events Semicolon-separated list of parameters of dial-up
service links related to the given account in a form
“ID/ l-ogin/password/CID/
CSID/flags" for each link
BLOCK_TYPE -1 Blocking type (see Blocking type; on page 143).
SLINK_LIST empty string Semicolon-separated list of service link ID s
related to the given account
EXTERNAL_ID empty string External account ID
BALANCE 0 Balance events Account balance
TECH_PARAM_TY 0 Add tech parameter, Tech parameter type: 
PE Modify tech 1 - web, 2 - email.
parameter and Delete
TECH_PARAM_ 0 Tech parameter ID
tech parameter
ID
TECH_PARAM_VA empty string Tech parameter value
LUE
TECH_PARAM_PA empty string Tech parameter password
SS
TECH_PARAM_ -1 Tech parameter type ID:
T_ID 1 - web, 2 - email.
SERVICE_TYPE Open session, Close Service type (see Types of services on
session, Add tech page 143).
parameter, Modify
tech parameter and
Delete tech
parameter
TARIFF_LINK_I 0 Add / Edit / Delete IP Tariff link ID
D traffic service link /
Video on demand
DISCOUNT_PERI 0 Accounting period ID
OD_ID
START_DATE 0 Staring date of a service link
END_DATE 0 Ending date of a service link
IP_GROUP_ID 0 IP group ID of a service link
IPTV_SERVICE_ empty string Add/Edit/Delete IPTV The contents of Custom options field in IPTV
DATA service link service parameters
IP_GROUP_LIST empty string Blocking events, Add Semicolon separated list of IP groups in a form
IP traffic link, Edit IP “address/mask/
traffic link and Delete login/password/MAC/NetFlow provider”
IP traffic link for each group
TIME_LIMIT 0 hotspot enabled, Remaining time of service for hotspot
hotspot disabled
TEL_LIST empty string Add telephony link, Semicolon-separated list of telephone numbers in
Edit telephony link, a form “number/ l-ogin/CIDs/incoming
Delete telephony link trank/outgoing
and Blocking events trank/pbx_id/password” for each number


141
Firewall rules 

Variable Default value Scope Description

NAS_ID empty string Open session и NAS ID
Close session
NAS_IP 0.0.0.0 NAS IP Address
SESSION_ID empty string Session ID (string)
ACCT_STATUS_T 0 Session status:
YPE 1 - open, 2 - closed.
CALLING_SID empty string Calling staton ID
CALLED_SID пустая строка Called staton ID
FRAMED_IP 0.0.0.0 IP address set in the Framed-IP-Address (8)
RADIUS attribute
BANDWIDTH 0 Set bandwidth limit Currently permitted bandwidth
(incoming), Edit
bandwidth
(incoming), Delete
bandwidth limit
(incoming), Set
bandwidth limit
(outgoing), Edit
bandwidth limit
(outgoing) and Delete
bandwidth limit
(outgoing)
PATH empty string Detailed statistics file Path to the log file or statistics file
closed and Log file
closed
PAYMENT_AMOUN 0 Payment Payment amount
T
PAYMENT_TYPE 0 Payment method ID
ACTION empty string User log events Action ID
COMMENTS empty string User log changes comments
WHO empty string ID of a user who initiated the changes
PASSWORD empty string HotSpot user User personal cabinet password
registration
TEL_NUMBER empty string User mobile phone number
TILL empty string User card existence time limit. When registering
again before the end of the period the existence
time is updated.
USW_IP Internet events Switch IP address in IP group properties
USW_LOGIN Switch login in IP group properties
USW_PASS Switch password in IP group properties
USW_REMOTE_ID Switch Remote ID in IP group properties
USW_ID Switch ID iin IP group properties
USW_PORT Switch port in IP group properties
UVLAN VLAN in IP group properties

SPLINK_ID, TRAFFIC_LIMIT, UTELLOGINS, UTELNUMBERS, and IP_LIST are obsolete and are not
used any more


142
Firewall rules 

The following enumerations may be used in some variables:

– Blocking type; – see Accounts on page 16.
– Types of services – see Services on page 18.

Events
Below is the list of events that may trigger a command:
– Turn Internet on – executes for each IP group in every IP traffic service link related to the given account when the
Internet status for this account is changed to On;
– Turn Internet off – executes twice for each IP group in every IP traffic service link related to the given account when
the Internet status for this account is changed to Off;
– Adding users – executes for the user being added to the system via the administrator’s interface or automatically;
– User modified – executes for the user whose data has been changed;
– Removing a user – executes for the user which is being deleted;
– Blocking events Block type changed – executes for an account on changing its blocking state (that is, on
blocking or unblocking);
– Balance events Balance notification sent – executes for an account when its balance passes by the threshold
defined by the system parameter notification_borders; Event is only executed if balance passes one of the
borders;
– Session events Session opened – executes for a service link on Accounting-Start RADIUS request;
– Session closed – executes for a service link on Accounting-Stop RADIUS request;
– Dialup events Dialup link added – executes for a dial-up service link on its creation;
– Dialup link modified – executes for a dial-up service link on changing its parameters;
– Dialup link deleted – executes for a dial-up service link on its removal;
– IP traffic events IP traffic link added – executes for an IP traffic service link on its creation;
– IP traffic link modified – executes for an IP traffic service link on changing its parameters;
– IP traffic link deleted – executes for an IP traffic service link on its removal;
– Telephony events Telephony service link added – executes for a telephony service link on its creation;
– Telephony service link modified – executes for a telephony service link on changing its parameters;
– Telephony service link deleted – executes for a telephony service link on its removal;
– Hotspot events Hotspot enabled – executes for a hotspot service link on user’s authorization;
– Hotspot disabled – executes for a hotspot service link on user’s logout or session stopping;
– Add hotspot user – executes for a hotspot user being added to the system via the web interface;
– Tech parameters events Tech parameter added – executes for a service link on creation of a technical parameter
(see : Technical parameters on page 36) related to it;
– Tech parameter modified – executes for a service link on changing a technical parameter related to it;
– Tech parameter deleted – executes for a service link on removal of a technical parameter related to it;
– Dynashape events Set bandwidth limit (incoming) – executes for each IP group on approaching the shaping
conditions (see Administrator’s interface: Dynamic shaping on page 77) imposed on the given service link for
the incoming channel;
– Edit bandwidth limit (incoming) – executes for each IP group on changing the shaping conditions imposed on the
given service link for the incoming channel (say, when the amount of traffic passes over the border limits);
– Delete bandwidth limit (incoming) – executes for each IP group on leaving the shaping conditions imposed on
the given service link for the incoming channel (say, when the amount of traffic is zeroed at the end of accounting
period);


143
Firewall 

– Set bandwidth limit (outgoing) – executes for each IP group on approaching the shaping conditions imposed on
the given service link for the outgoing channel (say, when the amount of traffic reaches the lower border limit);
– Edit bandwidth limit (outgoing) – executes for each IP group on changing the shaping conditions imposed on the
given service link for the outgoing channel;
– Delete bandwidth limit (outgoing) – executes for each IP group on leaving the shaping conditions imposed on the
given service link for the outgoing channel;
– Log file events Raw traffic file closed – executes for the detailed statistics file on its closing;
– Log file closed – executes for the log file on its closing;
– Making payment – executes when a payment is made;
– DHCP lease events New DHCP lease – executes on new IP address allocation (DHCP lease is offered);
– DHCP lease update – executes when a DHCP lease is updated;
– DHCP lease expire – executes when a DHCP lease expires;
– IPTV events IPTV link added – executes on IPTV service link creation;
– IPTV link modified – executes on IPTV service link modification;
– IPTV link deleted – executes on IPTV service link deletion;
– VoD link added – executes on VoD service link creation;
– VoD link modified – executes on VoD service link modification;
– VoD link deleted – executes on VoD service link deletion;
– Stoer user log – executes for any User log events.

Rules conversion
Firewall rules created in version 5.2.1-006 or earlier must be manually converted.

Firewall
Firewall is a system object used to identify an affector, a commutator, or a NetFlow provider.
The Settings: Firewalls page of the administrator’s interface lists the registered firewalls and contains the interface
for adding, modifying or deleting them.
Each firewall has the following parameters:
– ID – is assigned automatically.
– Type – is Local to execute the commands locally, or Remotte Cisco to execute them remotely over rsh. Must
conform to the firewall_type parameter set in the RFW config file of this firewall.
– Name – is a unique name to identify the RFW. Must conform to the rfw_name parameter set in the RFW config file
of this firewall.
– IP – is an IP address of NetFlow provider to be set in the properties of an IP group.
– Login – is a login to use as remote login in rsh authorization. Relevant only for the Remote Cisco type. The
local login is always set to netup.
– Comments – is an arbitrary comment.
An example of firewall creation is described in the Creating firewalls on page 110.

utm5_rfw settings
The utm5_rfw executable file is called /netup/utm5/bin/utm5_rfw.


144
utm5_rfw settings 

Possible command line parameters are:

-c <path> Config file path

-s <flags> Synchronize firewall rules on startup. Possible flags are listed at Synchronization of rules on
page 147.
-f Deprecated, superseded with -s enable
-o Deprecated, superseded with -s disable
-v Version number and parameter information

In the Win32 version of UTM5 RFW runs as a system service, so the command line parameters can not be used.
The sync_flags config file parameter may serve as a substitute for -s.

The following options for utm5_rfw startup on unix systems are available:
1. Direct start of the utm5_rfw executable with necessary parameters;
2. Start on watchdog with start parameter: 

/netup/utm5/bin/safe_utm5_rfw start

In this case the -f command line parameter is effectively passed to the executable. The script will restart
utm5_rfw automatically on failure;
3. Start via the automatic startup script (recommended).
on Linux:

/etc/init.d/utm5_rfw start

On FreeBSD or Solaris:

/usr/local/etc/rc.d/utm5_rfw.sh start

This will launch the watchdog script.

To stop the utm5_rfw and the watchdog script, execute:
on Linux –

/etc/init.d/utm5_rfw stop

on FreeBSD or Solaris –

/usr/local/etc/rc.d/utm5_rfw.sh stop

To start an RFW on a remote machine, it is essential that its config file parameters core_host and core_port
conform to the address and port used by the UTM5 core for Stream protocol connections.
Several RFWs may run on the same machine simultaneously, given that they have separate config and PID files.

Configuration file
By default, UTM5 RFW uses the config file /netup/utm5/rfw5.cfg.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.


145
utm5_rfw settings 

Below is the list of possible parameters.

ParameterPossib
le valuesDefault
valueDescription
Common parameters:
rfw_name string Mandatory Name of the UTM5 RFW by which it is known to the
parameter UTM5 core. Must conform to the firewall’s Name
parameter
core_host IP address Mandatory IP address of the host running UTM5 core.
parameter
core_port 1 to 65534 Mandatory Port where the UTM5 core listens to Stream
parameter (stream_bind_port parameter in the configuration
file).
rfw_login string Mandatory System user login to UTM5 core
parameter
rfw_password string Mandatory System user password to UTM5 core
parameter
firewall_type local, cisco local Firewall type. Must conform to the Type parameter of
the corresponding firewall In local mode all
commands will be executed locally, in cisco mode
they will be passed over RSH.
sync_flags see below not set Syncronization flags
Relevant for firewall_type=local:
sudo_path executable file not set Name of the sudo executable file
name
firewall_path executable file empty string Name of the executable file controlling the external
name software
firewall_ executable file empty string Script running on connection and reconnection to the
flush_cmd name core
dont_fork yes, enable, true (execute in Enables sequential execution, so that each rule will be
parallel) run after the previous one is completed.
Recommended to use along with ipt-ables
Relevant for firewall_type=cisco:
cisco_ip IP address Mandatory IP address to send the rsh commands to.
parameter

Logging parameters (for more details see System description: Logging on page 13):

ParameterPossible
valuesDefault
valueDescription
log_level numberfrom 0 to 1 Level of messages to be written to the log file
3
log_file_main file name standard error Main log file
stream
log_file_debug file name standard error Debugging log file
stream
log_file_critical file name standard error Critical log file
stream


146
utm5_rfw settings 

ParameterPossible
valuesDefault
valueDescription
rotate_logs yes, on, enable not set (rotation Enables log files rotation
off)
max_logfile_count number not set Maximum number of log files to keep
a. Действует, если (unlimited)
включена ротация
log-файлов.

max_logfile_size (a) size in bytes 10485760 Maximum size of log file

pid_file file name /var/run/utm5_rf PID file

w.pid
syslog_name string Not set Log entry prefix (when logging to syslog is
enabled)

The core_timeout parameter is deprecated and out of use.

Synchronization of rules
On automatic startup of RFW some rules may be executed in order to reinstall the configuration of the external
software. Only the rules related to the given RFW may be executed, and only on this RFW itself. The set of rules to
execute is defined by the flags (listed below).
The flags may be passed either via the config file parameter sync_flags or via the command line parameter -s, the
latter having higher priority. When several flags used simultaneously, they must be joined into a colon-separated string.
Available flags include:
– enable executes the rules related to the Internet on event;
– disable executes Internet off;
– users executes User added for all users;
– iptraffic executes IP traffic link added for all such links;
– dialup executes Dialup link added for all such links;
– blocks executes Block type changed for all accounts;
– shaping executes Set bandwidth limit for all IP groups.


147
Introduction 

UTM5 Dynashape 14
Introduction
UTM5 Dynashape module is intended to impose limitations on the user’s channel bandwidth. The bandwidth limit may
depend on time and on the amount of traffic consumed by the user.
The system core composes the firewall rules according to the settings, and passes them for execution to the external
software. The development of shaping control executables for the particular networking configuration to the
administrator’s area of responsibility. See the examples in Appendix: Approaches to traffic shaping on page 207.
Dynashape module requires a separate license. One may check the presense and validity of the license in the UTM5
administrator's interface (About > Licenses > Dynashape).

Workflow description
Shaping may be set up separately for each IP traffic service. The shaping settings include the collection of bandwidth
limitations and the associated parameters that determine the conditions to apply each limitation.
To set up shaping for a service:
1. Select the service ans set up the basic shaping parameters (see Administrator’s interface: Dynamic shaping on
page 77), including:
– types of IP groups to which the shaping applies (VPN or non-VPN);
– time range(s) when the shaping applies;
– border values of traffic amount, on passing which the limitations will be applied sequentially;
– bandwidth values for each time range and for each border value;
– traffic classes to which the shaping applies.
1. In case of shaping with the RADIUS attributes, provide these attributes on the same page. The dynamic adjustment
of attributes depending on the allowed bandwidth is enabled by the use of variables (see RADIUS parameters).
2. Set the firewall rules (see Administrator’s interface: Firewall rules on page 70) for the events Set bandwidth
limit, Edit bandwidth limit and Delete bandwidth limit for incoming and outgoing traffic, using the BANDWIDTH
variable which on application is substituted with the allowed bandwidth value.
The limitations are applied during the selected time range(s) to the IP groups of selected kind(s) and to the selected
traffic classes, according to the amount of traffic consumed by the given service link. On getting under the shaping
conditions, or on changing those (i.e. on starting the time range for which the shaping is set, or when the traffic amount
surpasses the given border), correspondingly, the Set bandwidth limit or Edit bandwidth limit event for incoming or
outgoing traffic occurs. In addition, the respective RADIUS attributes are sent and their previous values (if any)
removed. On running away from the shaping conditions (i.e. when the corresponding time range finishes, or when the
traffic amount is nullified at the end of accounting period) the Delete bandwidth limit event is executed and the
RADIUS attributes deleted.
When a new time range starts, the ensuing limitations are set within 5 minutes from the beginning of the said range.
The limitations due to consumed traffic amount are set after the next aggregation, which happens at regular intervals
defined by the traffic_agregation_interval parameter (see System core: Settings available in the administrator’s
interface on page 117).
In case of shaping by external scripts the UTM5 core passes to them the given bandwidth value as is. On the contrary,
in case of RADIUS attributes-driven shaping the input value is interpreted as Kbits/sec, and may be converted to other
units as well as to derivative values, see RADIUS parameters.
If a NAS supports Change-of-Authorization (CoA),requests, UTM5 RADIUS can send a CoA request to modify, apply
or delete bandwith limitations. A CoA request contains attributes allowing session identification (User-Name,
Framed-IP-Address, Called-Station-Id, etc.) and the new RADIUS parameter values. DAC secret, if set, will also be
included to the request.
CoA requests and responses are generated according to RFC 5176.


148
RADIUS parameters 

RADIUS parameters
The RADIUS attributes may include variables which get replaced with the respective values. calculated from the
bandwidth at given conditions.
Below is the list of available variables:

Variable Description Value (here W is the given

bandwidth)
IN_BANDWIDTH_BITS Incoming bandwidth in bits/sec W*1024
IN_BANDWIDTH_KBITS Same, in Kbits/sec W
IN_BANDWIDTH_MBITS Same, in Mbits/sec W/1024
OUT_BANDWIDTH_BITS Outgoing bandwidth in bits/sec W*1024
OUT_BANDWIDTH_KBITS Same, in Kbits/sec W
OUT_BANDWIDTH_MBITS Same, in Mbits/sec W/1024
IN_CISCO_NORMAL_BURST Incoming burst size in bytes 1.5*(W*1024)/8
IN_CISCO_EXTENDED_BURST Incoming extended burst size in bytes 1.5*2(W*1024)/8
OUT_CISCO_NORMAL_BURST Outgoing burst size in bytes 1.5*(W*1024)/8
OUT_CISCO_EXTENDED_BURST Outgoing extended burst size in bytes 1.5*2*(W*1024)/8


149
Warning 

UTM5 Urfaclient 15
Warning
The UTM5 urfaclient module provides direct interface for low-level operations which (unlike those performed via the
control center or the web interface)
may lack proper verifications or the coupled actions necessary to maintain the data integrity.
Therefore any urfaclient operation to be applied to the production system must be thoroughly checked in the test
environment beforehand.
NetUP does not assume responsibility for any possible losses caused by incorrect usage of the urfaclient module.

Introduction
The UTM5 urfaclient module is intended for the unified access to the core data structures via RPC interface (URFA).
UTM5 urfaclient is composed of the following parts:
– core library liburfa-client.so that provides the necessary means for the interaction of the utm5_urfaclient
utility and UTM5 core;
– utm5_urfaclient utility that actually performs the requested actions;
– schemes describing input and output parameters of the involved URFA functions;
– specific URFA scripts for any particular action or a sequence thereof.
Output of the executed URFA functions is directed to stdout.
Dynashape module requires a separate license. To verify the availability of the license, see About: Licenses in the
UTM5 administrator interface and check the list item denoted URFA client.

Scheme
The api.xml scheme contains XML description of the following:
– input and output parameters of various functions;
– action sequence, probably dependent on the parameters’ values.
Path to api.xml may be passed via the command line key -api. By default, it is /-netup/utm5/xml/api.xml.
Expression value is either the value of a variable, or the output value of a built-in function, or a constant, if neither a
variable nor a function with such name exist.
Variables are actually arrays of strings. When array index is not specified, zeroth element is assumed by default.
Interpretation of variables is context-dependent. Say, an integer tag implies parsing of string on return and serialization
on assignment.
All variables belong to the global scope, so care must be taken to avoid name conflict.
The built-in system functions are:
– now() returns string representation of current time in unix format;
– max_time() returns string representation of maximum possible time in UTM5 in unix format (2000000000, year
2033);
– size(varname) returns the length of the var_name array.

Tags available
– urfa – is a root tag. Has no attributes. May contain one or several function tags.


150
Scheme 

– function – describes a function. Mandatory attributes:

– name, the function name;
– id, the function ID.
Mandatory tags are: input and output (one for each function’s description) in arbitrary sequence.
– input – contains description of the function’s input parameters. Has no attributes. May contain an ordered sequence
of the following tags:
– integer
– long
– double
– string
– ip_address
– if
– for
– error
– output – is the same as input, only for output parameters of a function.
– integer – may reside either in input or in output. Contains 32-bit signed integer (int32_t). Must have the name
attribute with variable name. May also have attributes:
– default – default value. Relevant only for input parameters, in case if the corresponding variable with a name
set in the name property has not been found. If both the variable and the default value are absent, the program
will abort and return a non-zero error code.
– array_index – source or destination array index.
– long – is the same as integer, only for 64-bit signed integer (int64_t).
– double – is the same as integer, only for floating point number (double).
– string – is the same as integer, only for string parameters.
– ip_address – is the same as integer, only for IPv4 address (for example, 192.168.0.1 or 255.255.0.0) Internally
represented as int32_t.
– if – provides conditional operator in a sequence of parameters depending on the variable value. Must have the
following attributes:
– variable, which is the name of the variable to be checked;
– value to check against;
– condition to check (eq for “equal”, ne for “not equal”).
May contain an ordered sequence of the following tags:
– integer
– long
– double
– string
– ip_address
– if
– for
– error
Other nested tags are not allowed.
– for – provides loop operation. Must have the following attributes:
– name of the iterator variable;


151
URFA scripts 

– from (starting iterator value);

– count (number of iterations).
May contain an ordered sequence of the following tags:
– integer
– long
– double
– string
– ip_address
– if
– for
– error
Other nested tags are not allowed.
– error – causes exit with a non-zero error code. May have the following attributes:
– icode (exit code to return);
– comment (error description);
– variable to print out after the comment.

URFA scripts
URFA script describes a sequence of URFA function calls, loops and conditional operators in a form of XML tags. Each
action correspond to one file called <action_name>.õml.
Name of the directory containing URFA scripts may be passed via the command line key -x. The default value is
/netup/utm5/xml/. For example, the add_user action by default uses the file
/ne-tup/utm5/xml/add_user.xml.
URFA script must conform to the scheme.

Tags available
– urfa – is a root tag. Must contain an ordered sequence of the following tags:
– call
– parameter
– add
– sub
– mul
– div
– cat
– if
– for
– message
– out
– set
– error
– remove


152
URFA scripts 

– call – performs an URFA function call.

Must have the function attribute (name of the function to call).
May have the output attribute (if set to zero, XML output is blocked).
May contain parameter tags.Other nested tags are not allowed. 
Other nested tags are not allowed.
– parameter – Must have the name attribute (variable name).
May provide input value if contains the value attribute; otherwise defines a command line parameter.
If a variable is set both via the value attribute in the action file and via the command line, the latter has higher
priority. All values of the given parameter or its default value are placed in an array with name defined in the name
attribute.

Multidimensional arrays, whenever required, must be entered by means of the datafile (see Data files on
page 155).

Also may have the comment attribute containing the description of the variable which may be printed out via
combined use of the command line keys -a [action_name] and -help.
– add – is the tag of arithmetic addition. Must have the following attributes:
– arg1 – first addend,
– arg2 – second addend,
– dst – name of the variable to store the result.
– sub – is the tag of arithmetic subtraction. Must have the following attributes:
– arg1 – minuend,
– arg2 – subtrahend,
– dst – name of the variable to store the result.
– mul – is the tag of arithmetic multiplication. Must have the following attributes:
– arg1 – first multiplicand,
– arg2 – second multiplicand,
– dst – name of the variable to store the result.
– div – is the tag of arithmetic division. Must have the following attributes:
– arg1 – dividend,
– arg2 – divisor,
– dst – name of the variable to store the result.
– cat – is the tag of string concatenation. Must have the following attributes:
– arg1 – first string,
– arg2 – second string,
– dst – name of the variable to store the result.
– if – provides conditional operator in a sequence of parameters depending on the variable value. Must have the
following attributes:
– variable, which is the name of the variable to be checked;
– value to check against;
– condition to check (eq for “equal”, ne for “not equal”).
May contain an ordered sequence of the following tags:
– call
– parameter
– add


153
URFA scripts 

– sub
– mul
– div
– cat
– if
– for
– message
– out
– set
– error
– break
– remove
Other nested tags are not allowed.
– for – provides loop operation. Must have the following attributes:
– name of the iterator variable;
– from (starting iterator value);
– count (number of iterations).
May contain an ordered sequence of the following tags:
– call
– parameter
– add
– sub
– mul
– div
– cat
– if
– for
– message
– out
– set
– error
– break
– remove
Other nested tags are not allowed.
– message – must have the text attribute. Outputs a debugging message, defined in the text attribute, to STDOUT.
– out – must have the var attribute. Outputs a variable defined by var to STDOUT.
– set – sets the variable value. Must have the following attributes: dst and either src or value. Simultaneous use
of src and value is forbidden.
May also have the following attributes:
– dstindex is the array index for destination (0 assumed by default);
– srcindex is the array index for source (0 assumed by default);


154
Data files 

– dst defines the name of the destination variable (created if does not exist);
– src defines the name of the source variable;
– value is the expression to assign to the variable.
New element of an array may be written either to an existing element or to the next adjacent one (i.e. the element
with index equal to the current size of the array). Indexes start from 0. Calls to out-of-range elements cause
program abort.
– error – causes exit with a non-zero error code. May have the following attributes:
– icode, the exit code to return;
– comment (error description);
– variable to print out after the comment.
– shift – shifts the name array one step to the left, removing the first element. Usage not recommended.
– break – interrupts the innermost for tag execution and continues from the following line.
– remove – removes the whole array name, or its single element with index array_index, in case if the attribute is
given, otherwise the whole array is removed. In this case the subsequent elements are shifted left by one.

Data files
Data file describes an array or several arrays of data to be used as input parameter(s) in a function. Data file should
be passed to urfaclient via the command line key -datafile.

Tags available
– urfa – is a root tag. Must contain a sequence of array tags.
– array – is a top-level array.
Mandatory attributes:
– name (variable name).
– dimension (array dimension).
Also may have the comment attribute containing an arbitrary comment.
Must contain an ordered sequence of dim tags. 
Other nested tags are not allowed.
– dim – describes an array element, which itself may or may not be an array.
May have the comment attribute containing an arbitrary comment.
Must contain either a value or an ordered sequence of dim tags. 
Other nested tags are not allowed.

utm5_urfaclient utility
urfaclient is called as follows:
Launch UTM5 Urfaclient with the following command:

/netup/utm5/bin/utm5_urfaclient

Each command line parameter consists of the space-separated key-value pair, with the exception of the -help, -debug,
-u, and -dealer keys which require no value.
Most of parameters have their counterparts in the config file. The complete list of command line keys and config file
parameters is given below.
Besides that, some action-specific parameters are possible. Depending on the nature of the action, they may or may
not be mandatory.
All string values must be passed in UTF-8 encoding.


155
utm5_urfaclient utility 

Order of parameters is not important.

Configuration file
UTM5 Urfaclient uses the config file /n-etup/utm5/utm5_urfaclient.cfg.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
All parameters may be passed to the program via the command line as well. The command line parameters have
priority over those given in the config file and in the data file (if any).
The list of available parameters and command line keys is given below.

Key Parameter Default value Description

-h core_host 127.0.0.1 IP address of the host where UTM5 core is running.
-p core_port 11758 Port of the UTM5 core host listening to URFA
(urfa_bind_port parameter of the core
configuration file).
-l core_login init Login for accessing the UTM5 core
-P core_password init Password for accessing the UTM5 core
-x xml_path /netup/utm5/xml/ Path to the scheme and URFA scripts.
-api api /netup/utm5/xml/ Path to the scheme (if different from xml_path).
api.xml
-u plain_user not set If set to “yes”, makes urfaclient log in as plain
user. In this case, only the user functions may be
called (i.e. those with negative IDs); otherwise it is
vice versa
-dealer dealer not set If set to “yes”, only dealer functions may be
called-ssession_keynot setEnables persistent
sessions.
-s session_key not set Enables persistent sessions. Login and password
must be provided either in the config file or in the
command line parameters. Login and password
must be provided either in the config file or in the
command line parameters.
-i user_ip 127.0.0.1 When restoring a persistent session, denotes the IP
address from which the session has been
established initially.
-a n/a not set Action name (mandatory)
-c n/a /netup/utm5/ Path to the config file.
utm5_urfaclient.cfg
-help n/a not set Outputs help info. When used together with -a,
produces help on particular action (if available)
-debug n/a not set Enables additional debugging output, including the
inner variables’ values
-datafil n/a not set Path to the data file
e


156
Usage example 

Key Parameter Default value Description

-<имя> n/a not set Value of the function input parameter called
<name>

Usage example
Sample URFA scripts and other files are located at /netup/utm5/xml. Of all XML files found there, api.xml is the
scheme file, search_users_new_data.xml and teldata.xml are data files, and the rest are scripts.
Utility usage example:

utm5_urfaclient -a link_tariff_with_services -user_id 5

-account_id 5 -discount_period_id 2 -tariff_current 1
-ip_address 10.4.5.7 -iptraffic_login test4
-iptraffic_password 123

In this example a link_tariff_with_services.xml script is called, which attaches certain tariff plan to a
specified user account, together with attachment of all services having their Attach by default flag set.
The resulting output is directed to STDOUT.


157
Introduction 

Structured data import 16

Introduction
NetUP UTM5 supports data import in a form of XML files containing the following entities: users, telephone directions
and telephone zones. Some other entities may also be imported, albeit in a different way.
For importing traffic subclasses from CSV files, see Administrator’s interface: Traffic classes on page 43.
For importing traffic and phone call data from text files, see Text files import on page 132.

Interface
To import data:
1. From the top menu of the control center, select Menu: Import.
2. Press Browse and browse to the XML file.
3. Set the check boxes corresponding to the entities you want to import. (Other
entities contained in the file, if any, will be ignored.)
4. Press Import.
The imported XML file is checked for consistency to the scheme (see below).
Non-redundancy of entries and validity of internal cross-references (i.e. the existence
of entities referenced in the data being imported) are also checked. On success the file is imported into the database.
Otherwise, an error message pops up and the import operation doesnot occur.

XML file scheme

The full XML scheme is located at http://www.netup.ru/xsd/import.xsd. An example XML file is presented below in
Example XML file on page 164.
The XML tree of the file begins with the top-level import element containing users, zones, and directions nodes,
which in turn may include an arbitrary number of child nodes user, zone, and direction, correspondingly (see the
descriptions below).


158
XML file scheme 

Рис. 4. XML file scheme (users element).


159
XML file scheme 

Elements: user
Contains description of a user. May include the following elements (login and one account are mandatory, the rest is
optional):

ElementTypeDefault
valueDescription
id number Not set Account ID (reserved for future use). Not related to
the actual ID assigned to the user when recorded
into the database
login string Mandatory User login
element
accounts Collection of account elements (see account on page 161) 
Must be present and contain at least one element
password string not set Password
full_name string not set Full name
is_juridical 0, 1 0 1 – for a legal entity,
0 – for an individual
jur_address string not set Legal address
act_address string not set Actual address
district string not set District
building string not set Building
entrance string not set Entrance
floor string not set Floor
flat_number string not set Flat number
passport sting not set Passport data
house_id number not set ID of the house in UTM
work_tel string not set Work phone
home_tel string not set Home phone
mod_tel string not set Mobile phone
icq_number string not set ICQ
tax_number string not set Tax payer identification number
kpp_number string not set Industrial Enterprise Code
email string not set Е-mail
bank_id number not set Bank ID
bank_account string not set Bank account ID
comments string not set Comments
personal_manager string not set Personal manager
connect_date number not set Connection date in the Unix timestamp format
is_send_invoice 0, 1 0 Send invoice over email parameter (1 – yes, 0
– no).
advance_payment 0, 1 0 Advance payment parameter (1 – yes, 0 –
no).
switch_id number not set Switch ID


160
XML file scheme 

ElementTypeDefault
valueDescription
port_number number not set Switch port number
binded_currency_id number not set ID of the user’s preferred currency
parameters collection of parameter elements (see parameter on page 161)
groups collection of group elements (see group on page 161)

account
The account element may contain:

ElementTypeDefault
valueDescription
id number Not set Account ID (reserved for future use). Not related to
the actual ID assigned to the account once recorded
into the database.
is_blocked number 0 see Blocking type;
balance real number 0 Account balance
credit real number 0 Credit
vat_rate real number 0 VAT rate
sale_tax_rate real number 0 Sale tax rate
int_status 0, 1 1 Internet status
(0 – off, 1 – on).

Blocking type;
– 0 – not blocked;
– 256 – system block;
– 768 – system block, adjust recurring fee;
– 1280 – system block, adjust prepaid traffic;
– 1792 – system block, adjust recurring fee and prepaid traffic;

parameter
The parameter element must contain:

ElementTypeDefault
valueDescription
parameter_id number Mandatory ID of an additional parameter
element
parameter_value string Mandatory Parameter value
element

group
The group element must contain:

Element Type Default value Description

group_id number Mandatory ID of the group to which the user belongs
element


161
XML file scheme 

Elements: zone

Contains description of a telephone zone. May include:

Element Type Default value Description

id number not set Account ID (reserved for future use). Not related to
the actual ID assigned to the zone once recorded
into the database
name string Mandatory Zone name
element
zone_type number 0 Calls type: 
0 – local,
1 – внутризоновый,
2 – inner-zone,
3 – inter-city
directions collection of Mandatory, Each direction element must contain id element
direction though may be whose value is a number; these are the IDs of the
a. Are not empty included directions
related to the
second level
directio
ns element
described
above and it's
child
directio
n element,
described
below.

elements


162
XML file scheme 

Elements: direction

Contains description of a telephone direction. May include:

Element Type Default value Description

id number not set Direction ID. Used only for cross-references from the
zone elements within the same file. Not related to
the actual ID assigned to the direction once recorded
into the database
name string Mandatory Direction name
element
prefix string not set Same as called_prefix (left for backwards
compatibility; if both are set, called_prefix overrides
prefix)
called_prefix string not set Prefix or regular expression for checking the called
number
calling_prefix string not set Prefix or regular expression for checking the calling
number
zone_id number not set ID of the parent zone
incoming_trunk string not set Incoming trunk name
outgoing_trunk string not set Outgoing trunk name
pbx_id string not set PBX ID
calling_prefix_reg number 1 How to interpret calling_prefix:
exp 0 – prefix,
1 – regexp.
called_prefix_rege number 1 How to interpret called_prefix:
xp 0 – prefix,
1 –regexp.
skip number 0 1 – skip this direction (identify no calls into it)
dir_type number Same as in the Calls type: 
containing zone, 0 – local,
or 0 if zone_id is 1 – inner-zone,
not set 2 – inter-city,
3 – international


163
Example XML file 

A direction must be defined with at least one of the following elements: called_prefix, calling_prefix, incoming_trunk,
outgoing_trunk, or pbx_id.

Example XML file

Import of the example file given below creates the following entities in UTM:
– Telephone direction “Texas” defined by a regexp that checks that the called numbers are 11-digit and start with 1
followed by 713, 432, or 281.
– Telephone zone “USA” of type 3 (international) including the telephone direction “Texas”.
– User F.A.Cotton, an individual belonging to the group 2, with certain login and password, having one account with
balance of $ 20.5.

<?xml version="1.0" encoding="utf-8"?>

<import>
<users>
<user>
<accounts>
<account>
<id>1</id>
<balance>20.5</balance>
<vat_rate>0.10</vat_rate>
<int_status>1</int_status>
</account>
</accounts>
<id>11</id>
<login>cotton</login>
<password>aipsw123</password>
<full_name>F.A.Cotton</full_name>
<is_juridical>0</is_juridical>
<groups>
<group>
<group_id>2</group_id>
</group>
</groups>
</user>
</users>
<zones>
<zone>
<id>1</id>
<name>USA</name>
<zone_type>3</zone_type>
<directions>
<direction>
<id>1</id>
</direction>
</directions>
</zone>
</zones>
<directions>
<direction>
<id>1</id>
<name>Texas</name>
<called_prefix>^1(713|432|281)[0-9]{7}$</called_prefix>
<called_prefix_regexp>1</called_prefix_regexp>
</direction>
</directions>


164
Example XML file 

</import>


165
Introduction 

Dealer module 17
Introduction
Dealer module provides the interface for creating and operating dealers. The module consists of the following parts:
– core library liburfa-dealer.so containing the dealer functionality;
– part of the administrator’s interface responsible for handling dealers;
– dealer interface proper.
Dealer is a system object providing an ability to connect to the billing system and perform some administrative
operations regarding a particular subset of users. Dealer’s interface is a Java application based on UTM Control Center
and analogous to the administrator’s interface, but with limited functionality.
Creation and operation of dealers require a separate license. To verify the availability of the license and its term of
validity, see About: Licenses in the UTM5 administrator’s interface and check the list item denoted Dealer interface.
The creation of dealers and their abilities are described below.

Creating dealers
Creation of dealers is performed in the administrator’s interface under Users and groups: Dealers.
Technically, a dealer is treated by the system as if it were a system user hardwired to the special system group Dealers.
The properties of this system group (in particular, the list of permitted operations), as well as those of other system
groups, may be checked under Users and groups: System groups

The Dealers system group is built-in, so its properties can not be changed via the administrator’s interface.

Among other dealer’s properties there is an Access rights group of parameters that regulates the access of this
particular dealer to the following entities:
– Users (see Users on page 15);
– Accounting periods (see Accounting periods on page 18);
– Services (see Services on page 18);
– Tariffs (see Tariff plans on page 18);
– Houses (the list of registered buildings).
For each of these kinds, a list of options is provided to set up dealer’s access to each entity individually. By default the
access to all of them is denied, except for the users (if any) created by this very dealer.
The other available group of pages is the Reports group. There are reports for users who are assigned to the selected
dealer. The following reports are available in this group:
– General report (see General report on page 59);
– Traffic repor(see Report on blockings on page 62) t;
– Report on services (see Traffic report on page 60);
– Telephony report (see Telephony report on page 61);
– Sessions report (see Sessions report on page 62);
– Report on payments (see Report on payments on page 63);
– Report on services (see Report on services on page 60);
– Report on invoices (see Report on invoices on page 64).
Each user may be attached to only one dealer.


166
Dealer interface 

Dealer’s access to a particular user may also be set up on the user’s properties page using the Link to dealer button
(see ).
The creation of dealers and setting up their privileges are described in the following examples: Creating dealers on
page 109, Setting dealer’s permissions on page 109, and Linking users to dealers on page 110.
Once created and set up, the dealer may act as an administrator with limited rights in respect of the certain subsets of
users and other entities. In particular, a dealer may perform the following operations (see the corresponding examples
in Usage examples on page 99):
– Create and delete users;
– Change the user’s properties, except for the remote switch, preferred currency, technical parameters, group
attribution, and other dealers’ access to this user;
– Create, change, and remove accounts;
– Create, change, and remove service links;
– Create, change, and remove tariff links;
– Link users to houses;
– Make payments;
– Compose reports;
– Change own password.

Dealer interface

Installation and startup

1. Download the Dealer’s interface located in the client’s personal cabinet at https://www.netup.tv/en/utmoffice
(under Downloads > file utm_dealer.zip).
2. Unpack the archive on the dealer’s workstation.

Java Runtime Environment (JRE) version 8.0 (Java 1.8.x) or above is required in order to use the control center
JRE distributive is available for free at java.com .

3. Start the dealer's control center either by clicking on the file utm_admin.jar or
from the command line by executing 

java -jar utm_dealer.jar

The login dialog window similar to that in the administrator’s interface will appear.
4. Enter the IP address and colon-separated port number to connect to. If the port
number is omitted, the default value of 11758 is assumed.
5. Enter the login and password of the dealer specified at the time of its creation in
the administrator interface.
6. In the Settings group of parameters select the language to use.

Note that the selected language is not applied immediately to the login dialog itself. Instead, the language switch
occurs on the next launch of the program.

7. Check Save options if you want to save the parameters just entered (except for password) in the settings file for
use during subsequent launches. Check Save password if you also want to save the password as well.

It is highly recommended to change the dealer’s password immediately after logging in for the first time (see
Additional Features).


167
Dealer interface 

Items of the dealer interface are listed below by chapters, as they appear on the left pane. Users, Reports, Additional
features and About. Interface elements and their behavior are compatible with those described in Administrator’s
interface: Common features on page 32.

In contrast to administrators, dealers can't open and edit other dealers, system users, groups and system
groups.

Users
This page contains a list of users accessible for the dealer, containing the following info about each user:
– User ID – of the user.
– Login – is the user’s login.
– Primary account – is the account number.
– Full name – is the full name of the user or a title of the legal entity.
– Blocking type; – is the blocking status of the user.
– Balance – is the account balance.
– IP (VPN) and IP (non-VPN) – are the user’s IP addresses.
An interface for adding, editing, or removal of users, as well as making payments, is included.Dealer has neither editing
nor viewing access to the lists of dealers, system users, groups, and system groups.

The and buttons open the user details window similar to that of the administrator’s
interface (see Administrator’s interface: Users on page 33). The window includes a number of interface pages
accessible via the quick links on the left pane, which are gathered into the following groups:

User
– Main parameters: – includes login, full name, password, and the following elements:
– Payment in advance check box;
– Generate document for user button that displays the handout document for the user containing login, password,
and the provider’s contacts;
– Additional parameters – contains bank account data, etc.
– Contacts – includes personal data (address, phone, e-mail) of the contact person.
– Additional contacts – contains personal data of additional contact persons, if any.
– Additional info – is the view-only auxiliary information (dates of creation and last modification of the user).

Dealer has neither editing nor viewing access to the user’s group membership, contracts, preferred currency,
and technical parameters.

Tariffication
– Accounts – contains the list of the user’s accounts.
– Service links – contains the list of user’s service links.
– Tariff links – contains the list of the user’s tariff plans.
– Technical parameters – are the arbitrary parameters associated with the user. Their values may be used in the
commands for controlling the external software, which are sent by as a response to certain events, see UTM5 RFW:
Firewall rules on page 138.
While dealing with the user’s accounts, service links, and tariff links, the dealer may use only the explicitly stated subset
of services, tariffs, and accounting periods.


168
Dealer interface 

Reports
This group of pages contains interface for creating reports. The possible reports are the same as those listed in the
top-level group (see Reports on page 169), with the only distinction that they are based on the data related to the
currently selected user, rather than all users.

button removes the selected card user(s), once the related service links and tariff links are removed, or
displays an error message otherwise.

button opens the search window (see Search page on page 89).

button opens the payment window (see Payment page on page 88).

Reports
Dealer interface supports a variety of reports essentially similar to those presented in the administrator interface,
including:
– General report (see General report on page 59);
– Traffic repor(see Report on blockings on page 62) t;
– Report on services (see Traffic report on page 60);
– Telephony report (see Telephony report on page 61);
– Sessions report (see Sessions report on page 62);
– Report on payments (see Report on payments on page 63);
– Report on services (see Report on services on page 60);
– Report on invoices (see Report on invoices on page 64).
Reports for all users are limited to those users which the dealer has access to.
Unlike administrator, the dealer can not compose reports limited to custom groups of users.

Additional Features
This page contains interface for changing the dealer’s password. The Change button turns active only if New
password and Confirm new password coincide. If the passwords do not match, the Confirm button is unavailable.

About
This page displays the program version number and the general info related to the dealer.


169
Introduction 

Cashier module 18
Introduction
Cashier is a system user with the primary capability of making payments. Cashier’s interface is a Java application
based on UTM Control Center and analogous to the administrator’s and dealer’s interfaces, yet with even more limited
functionality.
Creation and operation of cashiers require a separate license. To verify the availability of the license and its term of
validity, see About: Licenses in the UTM5 administrator’s interface and check the list item denoted Cashier interface.
The license may or may not set a limit for the number of cashiers simultaneously connected to the UTM5 core.
The creation of cashiers and their abilities are described below.

Creating cashiers
Like other system users, cashiers are created via the administrator’s interface under Users and groups: System
users. A system group with appropriate permissions should be set up (see System groups on page 17) for the
cashiers. The necessary functions (see the list below) are grouped in a separate branch on the tree view.

FID Function name Description

0x1206 rpcf_search_users_new Searches for users
0x2006 rpcf_get_userinfo Returns information about a user
0x2026 rpcf_get_user_by_account Returns user ID for a personal account ID
0x2033 rpcf_get_user_account_list Returns the list of user IDs
0x212c rpcf_get_cashier_settings Returns cashier’s interface settings
0x2600 rpcf_get_accounting_periods Returns accounting periods list
0x2910 rpcf_get_currency_list Returns the list of currencies
0x3008 rpcf_payments_report_owner_ex Generates the report on payments made by the
current
0x3100 rpcf_get_payment_methods_list Returns the list of payment methods
0x3110 rpcf_add_payment_for_account_notify Makes a payment and emails the customer about it
0x440A rpcf_whoami Returns the current system user’s info
0x11112 rpcf_get_core_time Returns system time
0x1510 rpcf_get_accountinfo Returns personal account information
9

The subnet mask to login from may also be specified.

Besides the group-defined permissions, the s’ abilities depend on the interface settings (see Cashier interface on
page 82).
Once created and set up, a can:
– Make payments;
– Compose reports on payments.


170
Cashier interface 

Cashier interface

Installation and startup

1. Download the Cashier’s interface located in the client’s personal cabinet at 
https://www.netup.tv/en/utmoffice (under Downloads > file utm_cashier.zip).
2. Unpack the archive and run the utm_.jar file in a manner similar to starting the administrator’s interface (see ).

Java Runtime Environment (JRE) version 8.0 (Java 1.8.x) or above is required in order to use the control center
JRE distributive is available for free at java.com .

3. Start the cashier's control center either by clicking on the file utm_cashier.jar or from the command line by
executing 

java -jar utm_cashier.jar

The login dialog window similar to that in the administrator’s interface will appear.
4. Enter the IP address and colon-separated port number to connect to. If the port number is omitted, the default
value of 11758 is assumed.
5. Enter the login and password of the cashier specified at the time of its creation in the administrator interface.
6. In the Settings group of parameters select the language to use.

Note that the selected language is not applied immediately to the login dialog itself. Instead, the language switch
occurs on the next launch of the program.

7. Check Save options if you want to save the parameters just entered (except for password) in the settings file for
use during subsequent launches. Check Save password if you also want to save the password as well.
Items of the interface are listed below by chapters, as they appear on the left pane. Add payment and Payments.
Interface elements and their behavior are compatible with those described in Administrator’s interface: Common
features on page 32.


171
Cashier interface 

Payment page

Select a user in the search results to make a payment. The cashier can not access the complete list of registered users.
The search may be done by the user ID, account ID, login fragment, or name fragment (unless some of these options
are forbidden by the administrator). The number of users to display in search results may also be limited by the
administrator’s interface settings.
Payment method is set to Cash. Things left for the cashier to select are: account number, if the client got more than
one, currency (from the administrator-defined list) and the amount. Check Write out a receipt if you want to print a
receipt for the operation. One may add a comment to the payment in the Comment field.

Reports
Cashier’s interface supports the report on payments similar to that presented in the admin interface (see Report on
payments on page 63), except for:
– Only the payments made by this cashier are included;
– Selection by users group is disabled;
– The “Payment method” and “Received by” columns are removed as irrelevant;
– Context menu items “Print receipt” and “Roll back” are not available.


172
Introduction 

utm5_tray utility 19
Introduction
For a more convenient access to the personal account balance use the utm5_tray utility. This program runs on the
client PC and refreshes the balance information and data on remaining prepaid traffic periodically. Also, with this tool
the Internet access may be switched on and off. The utm5_tray utility is an alternative for the web interface (see Web
interface on page 177) which mostly covers the same functionality.

Installation and startup

1. Download user interface in the Customer area at https://www.netup.tv/en/utmoffice go to Downloads > file
utm5_tray.zip.
2. Unpack the archive on the user’s computer.

Java Runtime Environment (JRE) version 8.0 (Java 1.8.x) or above is required in order to use the control center
JRE distributive is available for free at java.com .

3. Start the dealer's control center either by clicking on the file

utm_admin.jar or from the command line by executing

java -jar utm5_tray.jar

The login dialog window will appear.

4. Enter the IP address and colon-separated port number to
connect to. If the port number is omitted, the default value
of 11758 is assumed.
5. Enter the login and password of the user specified at the
time of its creation in the administrator interface.
6. In the Refresh rate field enter the timeout for refreshing
the status information (in seconds), or leave the default
value.
7. In the Balance warning field enter the balance value (in
the user’s preferred currency) to issue a warning when
reached, or leave the default value.
8. In the Settings group of parameters select the language to use.

Note that the selected language is not applied immediately to the login dialog itself. Instead, the language switch
occurs on the next launch of the program.

9. Set the flags Enable Internet on connect and/or Disable Internet on disconnect if you wish to tie the connection
status to utm5_tray being started.
10.Set the flag Disable Internet on connection loss if you want the billing system core to disable Internet for you
upon loss of connection.
11.Set the flag Start minimized if you wish to minimize the utm5_tray window right after starting up.
12.Set the flag Connect by default if you wish to start utm5_tray on computer startup.
13.Press Connect. The main utm5_tray window will show up.
Once started, the program is represented by an icon in the system tray (see Tray icon on page 176). When the main
window is closed, the program still persists in memory and may be activated by double-clicking on this icon.


173
Interface pages 

Interface pages
The main window of utm5_tray contains several tabs with quick links at the top. The user’s access to particular tabs is
controlled by the administrator (see Administrator’s interface: Tray settings on page 81).

Main
The Main tab displays the following information:
– ID
– Login;
– Full name;
– Primary account number;
– Primary account balance;
– Primary account credit;
– VAT rate;
– Blocking type;
– Creation date;
– Internet status (with the ability to change it, unless
the account is blocked for running out of money).
Also, the page contains the following buttons:
– Details – opens the window with additional user info (passport data, address, contacts);
– Change user details – opens the window for editing user info. Name, address, passport data and the bank details
are write-only, that is, may be entered only once and can not be edited afterwards. The contact information (which
may include phone number, e-mail, web address, ICQ number) may be edited at any time.
– Change password – provides the interface for changing the user’s password.

Reports
The Reports tab contains interface for composing reports on given user, largely similar to that in the administrator’s
interface (see Reports on page 36).

The following types of reports are included:

– Traffic;
– Traffic grouped by date;
– Traffic grouped by IP;
– Services;
– Payments;
– Expiring payments;


174
Interface pages 

– Invoices;
– Telephony;
– VPN;
– Blockings;
– Internal transfer.
The user’s access to particular kinds of reports is controlled by the administrator (see Administrator’s interface: Tray
settings on page 81).

Payments
The Payments tab contains the following interface elements:
Under Card activation the user can make a payment by entering the number and
PIN code of the prepaid card.
Under Receipt the user may compose a receipt with arbitrary sum for printing.

Services
This tab contains the list of services attached to the user’s accounts. For each service, it contains For each service the
list contains its name, type, the tariff plan where it belongs (if any), accounting period, and price per period.

Messages
This tab contains interface for exchanging system messages. Its counterpart on the administrator’s side is described
in Administrator’s interface: Messages on page 41.

Accounts
This tab contains the balance of all user accounts. There are also buttons for changing the internet status and for
imposing voluntary blocking, if this is permitted by the administrator’s settings and the user balance is above the
required threshold.

Tariffs
This tab contains the list of user’s tariff plans. There are also buttons for viewing the tariff plan history and for switching
to another tariff plan, if this is permitted by the administrator’s settings and the user balance is above the required
threshold.

Connection
This tab contains the same interface elements as the login dialog window. Any changes are applied at the next launch
of the program.


175
Tray icon 

Tray icon
When utm5_tray is working, an icon appears in the system tray. Depending on the connection to the system core and
the Internet status, the icon may look as follows:

– – connection is being established (during the launch of the program).

– – connection established, Internet on.

– – connection established, some of the user’s accounts are blocked.

– – connection established, Internet off.

On mouse hover the icon displays a pop-up message containing the balance of the user’s primary account. Also, a
warning message pops up when the balance reaches zero.
The icon has a context menu of its own, which contains the following items:
– Open – activates the main window of the program.
– Enable / Disable Internet – turns Internet on and off.
– About – displays the program version number and contact info.
– Exit – closes the program.


176
Introduction 

Web interface 20
Introduction
provides web interface, where an end user may get a statement of account balance, make a payment via a prepaid
card, and perform some other activities. There is an alternative client covering the same functionality, which comes in
a form of a standalone program utm5_tray (see utm5_tray utility on page 173).

Installation
1. Download the server part of the user web interface from the customer area at https://www.netup.tv/en/utmoffice
( Downloads > file utm5_web_php.zip).
2. Unpack the archive on the web server.
3. In the web interface config file (see : Main on page 180) enter the address, port, login, and password for access to
the UTM5 core, as well as the path to where the archive has been unpacked.
4. In the PHP config file (commonly php.ini) set the following parameters:
– short_open_tag must be set to 1 (possible equivalents are: On, True, and Yes);
– time zone must be set correctly, for example:
date.timezone ='America/Chicago'

The web server must be capable of executing PHP files. Depending on the OS and on the PHP interpreter
version, installation of additional OpenSSL and PCRE extensions for PHP may be required.

Running the web interface requires PHP 5.4 or newer version. We do not recommend using other PHP versions.

Entrance page
To enter the web interface, launch an Internet browser, open the root page (by default, it is located at
h-ttp://your.server/utm5_web_php, where your.server stands for the domain name of the UTM5 server) and enter
the user’s login and password into the corresponding fields.
To enter using a prepaid card, enter the card number and PIN
for login and password. A card user will be created with login
card_NUM, where NUM is replaced with the card number.
User’s password is set to the card PIN.
To enter using hotspot, switch to the page Entrance (hotspot)
(unless you’ve been already redirected there automatically)
and enter the card number and PIN for login and password.
The session details page will show up to display the remaining
time, issued IP address and other session information.
Simultaneously, the page requested before will open in a separate window.


177
Interface pages 

Interface pages

Common

User
First tab contains the general
information, including user’s ID, login, full
name, creation date, summary balance
of all accounts, and state.
Additional tab contains more info on the
user, including address, contact
information, and bank details.

Edit tab contains the interface for editing

some of the user properties. Name,
address, passport data and the bank
details are write-only, that is, has to be
entered only once and can not be edited
afterwards. The contact information
(which may include phone number,
e-mail, web address, ICQ number) may
be edited at any time.

Accounts
This page contains info on all the user’s accounts. For each account, it displays its ID, balance, credit, tax rates,
blocking state and Internet state. Blocked amount is the sum of charges for the services not used because of the
account blocking, which is due to be returned to the user by the end of the period. Besides that, a number of actions
can be applied to any account:
– Return – immediately the blocked amount, if any;
– Switch internet on – (if it is off and the account is not blocked);
– Turn Internet off – (if it is on);
– Make promised payment – which is a credit payment with limited sum and fixed due date. A commission fee may
be charged for using this facility. The credit parameters (maximum sum, due date, minimum interval between
promised payments, minimum balance, commission fee, minimum balance to use the facility without fee) are set up
by the administrator (see : Promised payments on page 84).
– Voluntary suspension – which is a temporal suspension that a user may impose on oneself, for example, to save
the periodic fee for the time span when the service is not required. A commission fee may be charged for using this
facility. The suspension parameters (minimum and maximum time, minimum interval between suspensions, ability
to unblock oneself early, minimum balance, commission fee, minimum balance to use the facility without fee) are
set up by the administrator (see : Voluntary suspension on page 83). Note that after using a voluntary suspension
on oneself the user has to turn Internet on manually (this is done on the same page, see Switch internet onabove).
– Internal transfer – of funds between one’s accounts.

Password
This page contains the interface for changing the user’s password to all password-protected services, as well as to the
web interface itself.


178
Interface pages 

Messages
This page contains interface for exchanging system messages. The messages are divided into Incoming, Outgoing,
and New, and also can be filtered by time. Its counterpart on the administrator’s side is described in Administrator’s
interface: Messages on page 41.

Reports
This page contains the following user’s reports, each on a separate tab:
– Traffic report;
– Services report;
– Payments report;
– Invoices;
– Telephony report;
– Hotspot report;
– Blockings report;
– Internal transfer;
– Other charges.

Traffic classes removed by the administrator would still show up as existing in the web interface traffic report.

The functionality of reports is similar to that of the administrator’s interface (see Administrator’s interface: Reports
on page 59), except for the context menu.

Tariffs and services

Tariffs tab contains the list of user’s accounts together with the tariff plans linked to each. For each tariff plan, it displays
the start and end dates. The user may choose to switch to another compatible tariff plan (see Tariff plans compatibility
on page 18) starting from the next accounting period. A commission fee may be charged for using this facility (see :
Tariff switch on page 82).
Services tab contains the list of all services attached to the user’s accounts. For each service, it contains the start and
end dates, price, and the amount charged for the current period.
Tariff plan history tab contains the list of all tariff plans attached to the user’s accounts in the past.

Payments
Card activation tab page is where the user can make a payment by entering the number and PIN code of a prepaid
card.
Invoices tab contains the interface of generating a receipt for printing.
The rest of tabs (if any) contains the interface of making payments via various payment systems, one per tab. This
functionality is switched on/off and otherwise controlled by the separate config file, see : Payment systems on
page 181.

Exit
This hyperlink performs an immediate logout and returns to the authorization page.


179
Config files 

Config files

Main
By default, UTM5 web interface uses the config file located at /lib/config.php relative to the web interface root
folder. Below is the list of possible parameters.

Possible
Parameter Default value Description
values
$CONF_DEFAULT_MODULE1 string 00_user Default page after user login
$CONF_DEFAULT_MODULE2 string card Default page after card login
$CONF_DEFAULT_MODULE3 string hotspot Default page after hotspot login
$CONF_DEFAULT_LOGIN string 00_login Default page before login
$CONF_PATH string /utm5_web_php/ Relative path from site root to the
web interface
$CONF_WEB_USER string web System user login
$CONF_WEB_PASS string web System user password
$CONF_CORE_HOST IP address 127.0.0.1 Address of the UTM5 core host
$CONF_CORE_PORT Натуральное 11758 Port number to connect to the core
number
$CONF_LANG ru, en ru Web interface language
$CONF_REDIRECT_HOTSPOT 0, 1 0 Enables redirect after the hotspot
login to the previously requested
page
1 – enabled
0 – disabled
$DB_HOST IP address localhost UTM5 database host IP address or
domain name
$DB_NAME string UTM5 UTM5 database name
$DB_LOGIN string root Login name for DBMS connection
$DB_PASS string not set Password for DBMS connection
$DB_CHARSET encoding utf8 Database connection encoding
$LOG_DIR string /netup/utm5/log/ Web interface log directory.
$PAYMENTS_LOG_DIR string /netup/utm5/log/ Web interface payments log
payments/ directory
$PAYMENT_SYSTEMS_VISIBLE true, false true Show/hide payment systems page
in the user web interface.
true – enabled
false – disabled
$PAYMENTS_CHECKING_PERIOD Integer 86400 Checking period for lost payments
in seconds
$LOG_LEVEL Integer from 1 7 Level (type) of log events.
to 7
$HOTSPOT_TARIFF_ID Integer Hotspot tariff plan ID.
$HOTSPOT_POOL_ID Integer Hotspot prepaid cards pool ID.
$HOTSPOT_CHECK_IP true, false true


180
Config files 

Possible
Parameter Default value Description
values
$HOTSPOT_DURATION Integer 90000 Max Hotspot session duration.
$HOTSPOT_PHONE_REGEXP string 495[0-9]{7} Regular expression for checking a
telephone number
$HOTSPOT_PASSWORD_ALPHABET string qazxswedcvfrtgbn Character set used for Hotspot
hyujmkiolp123456 password generation.
7890QAZXSWEDCVFR
TGBNHYUJMKIOLP
$HOTSPOT_PASSWORD_LENGTH Integer 8 Password length.
$NBS_HOST IP address 127.0.0.1 Payment system integration
module host IP address or domain
name.
$NBS_PORT Integer 51010 Payment system integration
module host port.
$NBS_LOGIN string root Login name for payment systems
integration module connection
$NBS_PASS string root Password for payment systems
integration module connection
$KEYSTORE_FILE string lib/web-netup.ke Path to web-netup.keystore
ystore file
$KEY_PASS_FILE string lib/web-private. Path to web-private.pass fie
pass
$CONF_MEGOGO_ENABLED true, false false Enable/Disable Megogo
subscription page.
false – disabled
true – enabled
$CONF_MEGOGO_PAGE

Besides that, UTM5 Web interface configuration file may contain RentSoft integration parameters:
– $CONF_RENTSOFT_AG_NAME
– $CONF_RENTSOFT_SECRET
– $CONF_RENTSOFT_API_ADDR
These parameters are commented by default. For more information on configuring the RentSoft integration module,
please contact RentSoft support service .

Payment systems
A separate config file named /lib/payment_systems_config.php controls payment systems. It contains the
following parameters (among others):

Possible
Parameter Default value Description
values
$web_money_visible true, false false Switches on WebMoney support
$yandex_money_visible true, false false Switches on Yandex Money support
$chronopay_visible true, false false Switches on Chronopay support
$mobi_money_visible true, false false Switches on MobiMoney support
$web_creds_visible true, false false Switches on WebCreds support


181
Config files 

Each of the above-mentioned lines is followed by several parameters specific to the corresponding payment system.

Additional modules
Several modules located at /modules (in particular, the module of promised payments called
promised_payment.php and the internal transfer module funds_flow.php) contain some config parameters of
their own. The parameter named $MOD_VISIBLE. must be set to true in order to include the corresponding module
in the web interface.


182
Introduction 

Hotspot module 21
Introduction
Hotspot module is intended to provide Internet access paid by the hour. User authorization is performed using RADIUS
protocol or via the user Web interface (see Web interface on page 177). Operation of the hotspot module requires a
separate license. Verify the availability of the license and its terms of validity in the UTM5 administrator’s interface, see
About: Licenses in the administrator’s interface and check the list item denoted Hotspot module.
When using web interface for authorization, after entering card number and PIN, the page will update periodically to
keep the server aware that the service is still being provided. If the refresh does not happen in due time because the
user has closed the authorization page, the session expires. When the session is either expired or explicitly closed by
the user selecting Close in the menu, the Internet access is blocked and the user is charged for the session’s duration.
The expiration may also occur due to running out of money. The session lifetime is set by the hotspot_refresh_timeout
parameter (Settings > Parameters > Other settings).
To use the hotspot module, one has to create a tariff plan containing the hotspot service (see Hotspot service on
page 51). Price per hour may be time-dependent. A limited list of allowed networks to login from, as well as the
maximum connections number for the given login, may also be specified.
To use the hotspot module along with prepaid cards, it is necessary to create a pool of cards and connect them to the
tariff plan containing the hotspot service (see : Tariff ID on page 39). When issued a card, a user should in the first place
register it in Auto register user section of the web interface and thus obtain a login and password, which are
subsequently used for authorization in “Login to UTM (Card)” section (see Web interface: Entrance page on
page 177).
If the hotspot access has to be charged per traffic rather than per hour, the hotspot service must be linked to an IP traffic
service by checking the Dynamic IP address allocation option for both of them. At that, user authorization on the
UTM5 web interface would require the login and password stored in the properties of the hotspot service link.


183
Introduction 

DHCP 22
Introduction
NetUP UTM5 DHCP functions as a DHCP server. It receives messages and processes them according to RFC 2132.
It uses the following entities: switch type, switch, DHCP pools and IP Groups.
UTM5 DHCP allows one to associate a static IP address or a dynamic address pool with a MAC address, switch or a
certain switch port. UTM5 DCHP only allows to assign IPv4 addresses.

UTM5 DCHP only allows to assign IPv4 addresses.

UTM5 DCHP uses data from the database, communicates with the UTM5 Core via the Stream protocol and is able to
receive messages about changes in the database and the need to update certain information.
By default UTM5 DCHP works in not authoritative mode. That can be set up in the configuration file (is_authoritative
parameter).

You have to buy a separate license for this module, if you want to serve more clients.

Entities, used by UTM5 DHCP

1. Switch type - an entity that contains a certain switch type parameters. Those parameters are:
– Name – a string containing the name of the switch. Uniqueness is not mandatory, but is recommended
– Supported volumes – the number of ports for this switch type. May be several numbers, separated by commas
– DHCP option 82 parameters – description of DHCP option 82 parameters, used by this switch type for
composing DHCP requests:
– Remote ID – is the ID of the switch, acting as a DHCP relay, which the request came from
– Port – is the port number of the switch, acting as a DHCP relay, which the request came from
– VLAN ID – is the VLAN ID, if there is one
These parameters have properties like parameter type (string/binary), disposition, offset and length. These
properties are used to read those parameters from the option 82 of a DHCP request.
2. Switch - an entity that contains a certain switch parameters.
– Those parameters are: Name – is the name of the switch. One may use simple names that can help identifying
a particular switch. Uniqueness is not mandatory, but is recommended
– Actual address – is the actual address where one can find this switch
– Type – is the internal Switch type ID, which contains the parameters for this switch type
– Remote ID – is the Remote ID parameter of the DHCP option 82. It is used for composing a DHCP request. The
parameter type and its length are set in the corresponding Switch type
– Ports count – the number of ports for this switch type. This number is set on the Switches page of the Inventopy
group.
– Access parameters – are IP, login and password for the switch
These parameters may be used in the firewall rules (UTM5 RFW module), which have to do with sending
commands to the router. E.g. when one needs to turn off a switch port to prevent the customer from using Internet,
when the customer has run into debt.
These parameters are associated with the following variables:
– USW_IP
– USW_LOGIN
– USW_PASS


184
Entities, used by UTM5 DHCP 

– USW_REMOTE_ID
– USW_ID
– USW_PORT
– UVLAN
– SWITCH_IP
– SWITCH_PORT
For more details see UTM5 RFW: Variables on page 138
One can also add other DHCP options in the switch properties. These options and their values will be included in
the DHCP response if a DHCP client includes those options in the DHCP request.
3. DHCP pool- an entity that contains an IP pool parameters such as standard DHCP options that are used to form
the DHCP response when providing an IP address from this IP pool. The mandatory options are:
– Gateway
– Mask
– DNS server 1
– Lease time – is the lease time in seconds (lease time less than 3600 seconds is not recommended). Default
value is 86400 seconds (24 hours).
The nonmandatory options are:
– DNS server 2
– NTP server
– Domain
One can add extra DHCP options to the DHCP pool properties. These options and their values will be included in
the DHCP response if a DHCP client includes those options in the DHCP request.
The Gateway and Mask parameters are used to identify which DHCP pool does an IP address belong to.
IP address ranges are also a part of a DHCP pool properties. Every IP address range is defined by the first and the
last IP address.
Besides that there’s a Block action type for every DHCP pool. This parameter determines how a DHCP request
from a blocked user is processed. It allows one to provide IP addresses from this pool only to blocked users,
provide IP addresses from this pool despite of user being or not being blocked, or to ignore requests coming from
blocked users. Available options: Use blocked and Ignore request

If certain DHCP options are specified in a DHCP request, the DHCP response will include those options if their
values are set in the database. If no options are specified in a DHCP request, the DHCP response will include
all the options whose values are set in the database.

4. IP group - is a description of a network and its parameters, associated with an IP traffic service link. The IP traffic
is identified for the following tariffing and IP addresses are provided based on the IP group settings. An IP group
defines the link between a static IP address or a dynamic IP address pool and the following parameters:
– MAC address
– Internal switch ID
– Switch port
– VLAN ID
One needs to set a static IP address or a dynamic IP pool and set the values for the parameters named above to define
that link.

The static IP address ranges shouldn’t cross the dynamic IP address ranges. One shouldn’t use a static IP
address pool in one IP group and as a dynamic IP pool in another IP group. That may lead to an inappropriate
UTM5 DHCP behavior.


185
Processing a DHCP request 

Port and VLAN ID are DHCP option 82 parameters. UTM5 DHCP reads them according to the Switch type chosen
for the current switch.
After adding an IP traffic service link and adding an IP group containing parameters defining a link with an IP address,
a record of correspondence of a static IP address or a dynamic pool and those parameters will appear in the database.

Processing a DHCP request

When receiving a DHCP request, UTM5 DCHP compares the parameters of the request with the IP group’s parameters
from the database. The parameters priority is as follows: MAC address > Switch ID > Port > VLAN ID. The database
is sorted descending by these parameters and then the search is performed. Each database record contains
parameters for a single IP group.
UTM5 DHCP server only compares database records that contain one of the following sets of parameters:
– MAC address
– MAC address and Switch ID
– MAC address, Switch ID and Port
– MAC address, Switch ID, Port and VLAN ID
– Switch ID
– Switch ID and Port
– Switch ID, Port and VLAN ID
1. MAC address is compared first (if it is set in the database)
2. Then the DHCP server reads the option 82 parameters (if it is present in the DHCP request), based on the
appropriate Switch type parameters for the switch specified in the database record that is currently being checked.
3. If the parameters were read correctly, UTM5 DHCP server compares those parameters with the corresponding
parameters present in the database.
4. If one of the parameters is not present in the DHCP request, it is ignored for the comparison.
5. The comparison is considered to be successful if there are DHCP request parameters that match the
corresponding parameters from the database and there are no corresponding parameters that do not match.
After providing an IP address, UTM5 DHCP server adds a record, containing the IP address lease start date and the
lease time (lease time is set in the DHCP pool properties) to the database.

Configuration file
The default UTM5 DHCP configuration file for unix-systems is /-netup/utm5/dhcpd5.cfg and in windows UTM5
builds it is dhcpd5.cfg which can be found in the installation directory (by default it is
C:\ProgramFiles\NetUP\UTM5\).
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
The list of the possible parameters:

ParameterPossible
valuesThe default
valueDescription
database_type mysql, postgres mysql UTM5 database type
(mandatory
parameter)


186
Configuration file 

ParameterPossible
valuesThe default
valueDescription
database (mandatory UTM5 UTM5 database name
parameter)
database_host Database server localhost UTM5 database host name
IP/hostname
database_login string root Login name to access the UTM5 database
database_password string not set Password use to access the UTM5
database
database_sock_path file path /var/run/mysqld/ MySQL only. The path to the database
mysqld.sock socket file. This parameter is used if the
database_host parameter is not set or has
a “localhost” value.
database_port 1 to 65534 3306 MySQL only. The database server port
database_charset encoding utf8 MySQL only. Database connection
encoding
core_host IP address 127.0.0.1 UTM5 core host IP address
(mandatory
parameter)
core_port 1 to 65534 12758 Port which UTM5 listens for Stream
(mandatory messages (stream_bind_port
parameter) parameter in the core’s configuration file)
dhcp_login string dhcp Login name for UTM5 core access.
dhcp_password string dhcp Password for UTM5 core access.
dhcp_lease_expire_timeou time in seconds 1800 Minimum time after lease expiration that
t the IP address, assigned by the DHCP
may still be used
dhcp_lease_validation_pe tim in seconds 86400 Remaining lease time check rate.
riod
interface <interface not set List of interfaces, accepting DHCP
name>,<IP requests and corresponding IP
address>pairs of addresses. If the name of the interface is
parameters. eth0, there are two possible cases:
Add multiple 1) IP address is set (e.g. 10.0.0.1) - the
interfaces each server accepts only unicast requests to
at new string: address 10.0.0.1:67
interface=<interf 2) IP address is set to 0.0.0.0 - the server
ace name>,<IP receives broadcast requests, that come to
address> etc. eth0 (in Linux socket options
SO_BROADCAST and
SO_BINDTODEVICE are used)
is_authoritative yes, on, enable disabled DHCP server mode: authoritative or not
authoritative
load_log yes, on, enable disabled Load leases log at DHCP startup. The
default value should be good for most
systems
log_level Number 1 Determines the level of the messages that
0 to 3 get to the main message stream


187
Configuration file 

ParameterPossible
valuesThe default
valueDescription
log_file_main Path to file standard error The main message flow log file
flow
log_file_debug Path to file standard error The debug message flow log file
flow
log_file_critical Path to file standard error The critical error flow log file
flow
max_logfile_count Number Not limited Maximum number of stored log files.
max_logfile_size Size in bytes 10485760 The maximum log file size after which the
rotation triggers.
ping_retry_count Number 1 The ICMP request retries limit (see
use_ping).
rotate_logs yes, on, enable disabled Enables log file rotation
siaddr IP address Server IP The IP address of the next server
address participating in the download
use_ping yes, on, enable disabled If an existing lease is found when trying to
give an IP address to a client, send an
ICMP request to that IP address to find out
the actual status of the client.
use_old_lease yes, on, enable disabled Renew lease for a particular MAC address
in case the DHCP option 82 parameters
can’t be matched.


188
Introduction 

IPTV integration module 23

Introduction
The IPTV integration module is intended for integration with an IPTV system. When using it with NetUP IPTV system,
this module allows one to grant access to IPTV contents and content groups and choose the content explicitly when
creating a service. It also allows one to create IPTV access cards and generate activation codes for those cards.
When using this module with some other IPTV system, one has to use UTM5 RFW events and third party scripts to
control user’s access to IPTV contents.
The module requires a separate license. To verify the availability of the license and its terms of validity, see in the UTM5
administrator’s interface and check the list item denoted IPTV module.

Common features
The integration module interacts with IPTV middleware. In order to let the module connect to NetUP IPTV Core, the
DNS server on the UTM5 server should be able to resolve IPTV domain names. All the other billing systems interacting
with the IPTV cluster core must be disabled.
NetUP IPTV system uses access cards for client authorization. One needs an access card to access IPTV services.
The integration module allows one to create access cards and generate activation codes.
Client's TV channel access is managed by interacting with the NetUP IPTV Middleware system. When UTM5 needs
to grant access to media content, e.g. when an IPTV service is attached to client’s personal account, it sends a request
to IPTV middleware to grant access to certain media content to access card owner for an unlimited period of time. When
it needs to prevent a user from accessing the content (e.g. when an IPTV service is unattached from user’s personal
account or when user switches tariff plan), UTM5 requests from IPTV middleware to set access end time for user’s
access card to that media content to current time, which means that the content becomes no longer available.
Buying the module license makes IPTV service type available.
The process of UTM5 setup for integration with NetUP IPTV system is described below.

Connection
In order to connect to NetUP IPTV Core, open UTM5 configuration file and set the following parameters:
– iptv_cluster_host – is the IP address of NetUP IPTV Core
– iptv_cluster_port – is the port which NetUP IPTV Core is listening to for billing system connections

For proper operation the UTM5 server must resolve db.iptv to the IPTV cluster core IP address


189
Connection 

Open IPTV administrator's web interface and go to the Services page:

If NetUP IPTV Billing service is running, left-click on it’s name to open a dialog window. Press Yes when that window
appears to stop the service.

After that go to the Connections page and left-click the IP address next to the NetUP IPTV Billing connection name.

In the Change Server Host window that will open, press Auto detect to reset the information about the billing system.

Now launch UTM5. After that go to the Connections page of the IPTV administrator’s web interface and make sure that
NetUP IPTV Billing is connected and the IP address matches the IP address of the server that is running UTM5.

If the UTM5 core was running while the NetUP IPTV Core connection setup, restart it after finishing the setup
process


190
Creating and attaching IPTV service 

Creating and attaching IPTV service

First one needs to create an IPTV access card:
1. Open UTM5 administrator’s interface and go to the Users page
2. Choose a user and press
3. Once the User properties window opens, go to the Accounts page in the Tarrification group
4. Choose an account to which you plan to attach IPTV service and press The account properties
window will show up:

5. Once Account properties window opens, press next to the IPTV access card parameter. Access
card number will appear in the parameter field

One can find an activation code for the access card on IPTV activation codes page in Tariffication group.

Now create a new service (for more information see Usage examples: Creating services on page 101). Go to the
Service parameters page choose NetUP as an IPTV system and choose a media content or a group of media contents
which a user, to whose account this service will be attached, should be provided access to.

Create an IPTV service template to be able to add it to a tariff plan

After that one can attach this service to a user’s account like any other
periodic service (see Usage examples: Creating service links on
page 105). If an access card had not been created beforehand, one can
create it at the service attachment and service link creation stage. In the
service link creation window press beside the IPTV access
card parameter.


191
Introduction 

IP telephony module 24
Introduction
The IP telephony module is intended for processing authorization requests and consumed services accounting for
voice gateways, gatekeepers and voice proxy servers. It supports both traditional and IP telephony.
The data to be accounted for may be based either on UTM5 RADIUS server requests (see UTM5 RADIUS on
page 119) or on CDR files parsed by the utm5_send_cdr utility (see Text files import on page 132).
The module requires a separate license. To verify the availability of the license and its terms of validity, see About:
Licenses in the UTM5 administrator’s interface and check the list item denoted Telephony module.

List of terms
– IP telephony – is a general term denoting voice transmission over networks via IP. Also known as: Voice over IP,
VoIP, Internet Telephony.
– PSTN – is a Public Switched Telephone Network. This notion includes local and national telephone networks.
– Caller ID – is a phone number of a caller. ANI is Automatic Number Identification.
– VoIP gateway – is a device with an IP port and also (if required) ports to connect to PSTN. Usually the device is
used as a gateway between PSTN and IP network. Cisco router 3620 with the NM-2V + VIC2FXO module may serve
as an example of a device of this type.
– H.323 – is a standard offered by the International Telecommunications Union (ITU-T) describing principles of IP
telephony networks. The standard describes the protocols associated with IP telephony equipment registration
(RAS – Registration, Admission and Status), call setting-up (H.225.0, H.245), voice transmission, user
authorization, etc.
– H.323 gatekeeper – is responsible for registration of terminal equipment (gateways, client devices), access rights
control, distribution of numbers. Almost all gatekeepers can process authorization and transmit statistics on
telephone calls via RADIUS protocol.
– Codecs – are the sound compression algorithms on the transmission side and decompression on the receiving
side. Generally are used to minimize network traffic. That's why codecs are usually characterized by the bandwidth
required for voice transmission using this codec. Uncompressed voice transmission takes 64 Kb per second.
Codecs with high compression ratio require powerful computing resources. That's why encoding of a large number
of voice flows requires usage of special microprocessors (DSP, digital signal processor).

CodecBit rate,
Kbit/secQuality
G.711 64 High
G.723.1 5.3 – 6.4 Medium
G.729 8 Medium

– IVR – is Interactive Voice Response. Represents a technology of voice menu and is widely used for authorization
of PSTN users to call via IP telephony.

Workflow description
RADIUS requests concerned with telephony are recognized by the system based on the cisco-h323-conf-id attribute.
If it is missing, the request is interpreted as related to dialup service.


192
Network organization schemes 

To register a caller, a gateway sends to the RADIUS server a registration request containing the Calling-ID (31) and
caller’s login, but no Called-ID (30). The RADIUS server in turn searches for the telephony service link which is
identified by the login in its properties (see : Login on page 95). If the link in question is not found or the corresponding
account appears to be blocked, the registration is denied. Otherwise, an affirmative response is sent, which may also
contain the user’s phone number if it is set in the service link properties.
To authorize a call, a gateway or a voice gateway sends to the RADIUS server a registration request containing the
Calling-ID (31) together with Called-ID (30). The RADIUS server in turn searches for the telephony service link which
is identified by the login in its properties. If the link is not found, or the account is blocked, or the call parameters do
not match those of any direction covered by the service, or the current time is not covered by the service, the registration
is denied. Otherwise, an affirmative response is sent, which also contains the maximum duration of a connection. The
maximum duration is calculated either as the time left till the end of time range covered by the service (unless the
service provides round-the-clock coverage), or as the time till the account’s balance runs out given its current balance
and the current connection price per minute (which may also be time-dependent), whichever of these happens sooner.
To account for a call, a gateway or a voice gateway sends to the RADIUS server an Accounting-Start request containing
the Calling-ID (31), Called-ID (30), and probably the starting time. If the starting time is not provided, the arrival time
of the Accounting-Start request is assumed instead. The RADIUS server in turn searches for the telephony service link
which is identified by the login in its properties. If the link is not found, the request is ignored. Otherwise the connection
price per minute is determined, which may depend on the telephone direction and current time. If the call parameters
do not match those of any direction covered by the service, or the current time is not covered by the service, the call
is accounted for by zero price. When a call finishes, an Accounting-Stop request is sent containing the Calling-ID (31),
Called-ID (30), and probably the call duration and/or its finishing time. Then the RADIUS server accounts for the call
considering its duration and the price per minute. If the call duration is not provided, the difference between the finishing
time and starting time is assumed instead. If the finishing time is not provided, the arrival time of the Accounting-Stop
request is assumed instead. If the price per minute is time-dependent and does change during the time span in
question, the call is split into parts of constant price and accounted for in parts. The charge-off information is passed
to the UTM5 core.
The calls lacking an Accounting-Stop request may be either ignored or considered finished by timeout based on
Interim-Update requests and accounted for accordingly, depending on the RADIUS server settings.
If the gateway does not support the Accounting-Request communication with the RADIUS server, it may dump the
phone call information to text files to be parsed later by the utm5_send_cdr utility (see Text files import on
page 132). This utility parses log files, retrieves individual calls and sends those to the UTM5 core using URFA.

Network organization schemes

A VoIP gateway connecting PSTN to an IP network organizes voice traffic conversion from IP network to PSTN. Thus,
a user with an IP phone or a PC with a software phone installed (Microsoft NetMeeting, OpenPhone etc.) may give a
call to a subscriber of PSTN.
Similarly a subscriber of PSTN may call a network user. For that it is required to dial the gateway phone number in
PSTN (9391000 on the scheme) and then, after authorization (if the mechanism is enabled on the gateway) dial an
internal number of an IP network user (numbers 100 and 200 on the scheme).


193
Network organization schemes 

In the scheme containing the H.323 gatekeeper, all devices should register on the gatekeeper. At that, authorization
may be processed via RADIUS protocol by using the common Access-Request scheme.

As a result the gatekeeper has a table with IP addresses and numbers of all network devices. All calls begin with
addressing to the gatekeeper for conversion of dialed numbers to IP addresses. For that the gatekeeper requests of
the RADIUS server to authorize the call and pass the filled in attributes Called-Station-Id (30) (dialed number) and
Calling-Station-Id (31) (a number of a calling subscriber). At that the RADIUS server checks a user balance, tariff plan
for a called direction and, if all is OK, gives the Access-Accept packet in which it may set the maximum connection
duration for the user calling to the certain direction. Usually this information is set in the h323-credit-time, vendor 9
attribute (Cisco).
In case authorization is successful (and after all parameters are coordinated) the connection between a called and a
calling station is established. At that the gatekeeper sends a packet (Accounting-Start) containing parameters for the
established connection to the RADIUS server.
In case both stations are in the same network the connection is being established directly. If the called station is in
another network then the connection is established via one of the gateways. Another variant is also possible, when a
user communicates with the gatekeeper only. In this case the gatekeeper acts as a proxy server and real IP addresses
of the stations are hidden. This scheme may be applied if the direct line between the stations is worse (e.g., serious
IP packets loss or a delay) than between the gatekeeper and both of the stations.
When the connection is finished the gatekeeper sends a packet containing information about the call to the RADIUS
server. In the packet it specifies the connection duration, a cause of the connection break and other parameters. Using
these data the RADIUS server rates the session, charges the user and puts a record in a log file.
Authorization of PSTN users may be done using IVR as follows:
1. A user of PSTN dials a local number of IP telephony access. The call is accepted by an IP telephony gateway (e.g.,
Cisco 3640 with E1 module) connected to the line.
2. The gateway loads an audio file (usually of the .au type) with an invitation record and plays it to the user. Usually
it prompts the user to enter a number and a PIN code of a prepaid telephone card.
3. After a special digit combination is entered, the authorization is being processed on the R-ADIUS server. At that,
the card number and PIN code are usually recorded to the attributes 1 (User-Name) and 2 (Password).


194
Network organization schemes 

4. In case of successful authorization the RADIUS server sends an Access-Accept packet with the user balance. For
that the attributes h323-credit-amount and h323-currency with vendor=9 (Cisco) are used. IP telephony gateway
loads appropriate voice files and in this way informs the user of his balance and invites to enter a telephone
number. Note that usually IP telephony is profitable for remote calls (national and international calls).
5. After the number is entered it is processed through second authorization on the RADIUS server. At that, an
attribute Called-Station-Id containing the dialed number is transmitted additionally. Depending on the balance and
connection cost per minute, the RADIUS server calculates the maximum available session duration and sends the
value in the Access-Accept packet attribute h323-credit-time. If the Called-Station-Id attribute is missing, the
R-ADIUS server returns h323-return-code (9,103) attribute with the following meaning:
– 0 – means that the user is active;
– 1 – means that the user does not exist;
– 2 – means that the user is blocked.
1. After the affirmative reply is received from the RADIUS server, the IP telephony gateway establishes connection with
the called user. The connection will break if the session duration exceeds the maximum calculated in the previous
step.
2. On establishing the connection an Accounting-Start packet is sent on the RADIUS server. On breaking, the
Accounting-Stop packet is sent.


195
Introduction 

UTM5 Traffic collector 25

Introduction
This module gathers the IP traffic data in NetFlow format, converts it to internal UTM5 format and classifies it. Using
additional traffic collectors decreases the UTM5 core server load and allows one to correctly process information from
NetFlow providers from subnetworks with crossing adress spaces. The executable file utm5_traffic_collector
is located in /netup/utm5/bin.
In standard UTM5 configuration a single System traffic collector is available. A separate license is required in order to
use additional traffic collectors. Check the license expire date and the max available traffic collectors for the current
license in the UTM5 administrator’s interface (see : LicensesUTM core).
Go to the Settings group, Traffic collectors page of the administrator’s interface for the traffic collector and UTM5 core
interaction settings (see Traffic collectors on page 80).

Configuration file
By default, UTM5 Traffic collector uses the config file /netup/utm5/utm5_traffic_collector.cfg.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
The list of the possible parameters:

Parameter Possible Default value Description

values
core_host IP address 127.0.0.1 IP address of the UTM5 core host.
(mandatory
parameter)
core_port 1 to 65534 12758 Port that UTM5 core listens to for Stream
(mandatory messages (stream_bind_port parameter of
parameter) the configuration file).
tc_login string collector Login for UTM5 core access. Is set on the System
users page of the administrator’s interface.
tc_password string collector Password for UTM5 core access. Is set on the
System users page of the administrator’s
interface.
tc_name string traffic_collector Is a unique traffic collector name. Is set on the
Traffic collectors page of the administrator’s
interface
nfbuffer_host string 0.0.0.0 Is the IP address on which the UDP port for
receiving UDP packets will be listened to.
nfbuffer_port string 9997 Port that the core uses to receive NetFlow
nfbuffer_bufsize Integer Set by OS The size of the UDP socket buffer used to receive
the NetFlow stream.
log_level number 1 Specifies the level of messages that get to the log
0 to 3 message stream.
log_file_main path Standard error Main log file.
stream


196
Configuration file 

Parameter Possible Default value Description

values
log_file_debug path Standard error Diagnostic and debugging information log file.
stream
log_file_critical Путь к файлу Standard error Critical error log file.
stream
rotate_logs yes, on, enable Rotation enabled Enables log file rotation.
max_logfile_count number not limited Max number of stored log files
max_logfile_size Size in bytes 10485760 Log file size limit that, when reached, triggers
rotation.
tc_pid_file path /var/run/utm5_traffic Traffic collector PID file path.
_collector.pid


197
Introduction 

Automatic registration of users 26

Introduction
UTM5 has two options for activating the prepaid Internet cards and receiving the dial-up service: guest access or
conventional access with automatic registration of users. In the first case, the guest login and password are used to
register in the system. After registration the user enters the system with one’s own access parameters. After registration
the user enters the system with one’s own access parameters. In the second case the user enters card number and a
pin code as a login and password for dial-up connection, and then is automatically registered and gets access to the
Internet right at once.
For automatic registration of users using the options above, you have to generate the tariff plan and connect the dial-up
service to the user with the corresponding connection cost.
On creating the tariff plan you have to generate the prepaid cards pool and bind it to the tariff plan.

Guest access
If you use guest access you have to generate a user with a login and a password known beforehand. For example,
login guest and password guest.
These settings should allow the guest access only to the web-site to activate the Internet-card. The session time can
be also restricted, say, to 600 seconds.
It is necessary to create a Dialup access service with pool GUEST, maximum connection timeout of 600 seconds, and
connection cost of 0 c.u. (currency units) per hour.
Then you have to generate a pool of IP addresses with login GUEST and certain-range addresses, e.g., 172.16.0.0/16,
on the router or in UTM. The router settings should allow this range of users to get access only to the DNS and to the
web server to activate the card. For the safety sake it is better to arrange an isolated DNS server, not connected to the
Internet and containing only the records, which the user will need to access the registration web server.
On login the registration web server the user selects the Automatic registration of user menu item and enters the
data from the Internet-card. If the data is entered correctly and the card was not activated or blocked in the past, a new
card user will be generated in UTM automatically, and the user will receive the login and password info for connection
in dial-up mode. By selecting the Login to UTM menu item and entering the login and the password received after the
registration the user may get access to his personal office and account statistics.

Access with automatic registration

The immediate access with the prepaid cards requires RADIUS server additional tuning. In RADIUS server
configuration file /netup/utm5/radius5.cfg define the option:

radius_card_autoadd=yes

Restart the server. RADIUS server will automatically register the user in UTM at his first attempt to get access on
prepaid card.
In order to receive access the user should enter the card number as login and its pin code as a password on every
connection. If the user connects with this card at a first time RADIUS server will register him automatically and connect
him to the Internet right at once. On every new connection the user would have to enter the card number as a login
and the PIN code as a password. When the card expires (balance turns red), the user has to activate a new card.
This kind of automatic registration is possible on authorization using PAP protocol only. This method is used by
Windows by default for modem connections and requires no additional settings. However, sometimes the users'
configuration should be changed to let them be registered automatically.
If access settings for the user automatic registration are correct the following records should appear in the RADIUS
server log file on the first connection:

?Debug: Oct 27 12:08:00 RADIUS Auth: Packet from <example.org>


198
Access with automatic registration 

?Debug: Oct 27 12:08:00 RADIUS Auth: User <5> connecting

ERROR: Oct 27 12:08:00 RADIUS DBA: Can't find login <5>
ERROR: Oct 27 12:08:00 RADIUS DBA: Can't find card login <000000005>
?Debug: Oct 27 12:08:00 RADIUS Auth: Attempt to add new Card user: <5>
?Debug: Oct 27 12:08:00 RADIUS DBA: Sending Auto-Add Request for Card-ID: 5
?Debug: Oct 27 12:08:00 RADIUS URFA[plugin]: DLink: SLID/SID/AID: 14/6/14
?Debug: Oct 27 12:08:00 RADIUS URFA[plugin]: Account <14> with balance <10.000>
?Debug: Oct 27 12:08:00 RADIUS Auth: Got AutoAdd 14 UID from core.
ERROR: Oct 27 12:08:00 RADIUS DBA: Can't find login <5>
?Debug: Oct 27 12:08:00 RADIUS DBA: login_store iter->second.dialup.session_count:0
Info: Oct 27 12:08:00 RADIUS Auth: User <5> added.
?Debug: Oct 27 12:08:00 RADIUS Auth: Auth scheme: PAP
?Debug: Oct 27 12:08:00 RADIUS Auth: PAP: <51154755> vs <51154755>
?Debug: Oct 27 12:08:00 RADIUS Auth: PAP: Authorized user <5>
?Debug: Oct 27 12:08:00 RADIUS Auth: Dialup session limit:0 session count:0 for user:5
?Debug: Oct 27 12:08:00 RADIUS Auth: Calculated maximum session time: 36000
?Debug: Oct 27 12:08:00 RADIUS DBA: dialup_link_up-date called for slink:14
?Debug: Oct 27 12:08:00 RADIUS DBA: soft dialup_ link_update for slink:14 session_count:1


199
Introduction 

E-mail notifications 27
Introduction
UTM5 may send automatic e-mail messages to the users (or rather those of them who has valid e-mail addresses
entered in their user info) for a number of reasons. Global system parameters related to e-mail are described in
Settings available in the administrator’s interface on page 117.
The messages are sent via SMTP server set by the smtp_relay parameter. The SMTP server must be set up correctly
and must send every incoming message within 1 second. Longer delays in email processing may drastically reduce
the billing performance. It is recommended to use the local SMTP server.
Possible types of e-mail messages include:
– Invoices – are sent when either an invoice is issued to a user having the Send invoices by email parameter
checked (see : Contacts on page 35), or when the Send by email context menu item is hit in the report on invoices
(see Report on invoices on page 64). Message subject is set by the invoice_-subject system parameter.
Message text is set by invoice_text, while the invoice itself is contained in an attachment as an HTML file. The
invoice is generated on the basis of the Invoice document template (see Document templates on page HIDDEN).
– Payment notifications – are sent on the event of a payment being made, if the corresponding parameter is
checked in the payment’s properties (see : Send email notification on page 88). Message subject is Payment
nofication. Message text is composed from the template stored in the payment_notification_message
system parameter.
– Balance notifications – are sent when the user’s balance (not considering the credit) crosses the borders defined
by the notification_borders system parameter, if the latest is set. Message subject is defined by the
notification_message_-subject system parameter. Message text is composed from the template stored in
the notification_message system parameter.


200
Database backup 

System maintenance 28
Database backup
This is normally done with the standard tools specific to the particular kind of DB server. To prevent possible loss of
data, it is recommended to make backup copies of the database regularly (say, monthly). Besides regular backups, it
is also advisable to make an extra copy before any low-level operation on the database, like archiving of tables, direct
manual intervention, debugging of urfaclient scripts, etc.
The backup copy may be either brief or full. The latter one contains all tables, while the former one omits the charge-off
tables. It is recommended to stop the UTM5 core while creating a full backup copy (which may take considerable time,
due to the excessive size of charge-off tables). Otherwise prolonged blocking of tables may lead to core crash.
For large projects, where the tables are especially huge and yet it is critical to keep downtime low, we recommend the
use of a slave DB server, which makes it possible to create a backup copy without shutting down the billing.

Database integrity verification

Once the UTM5 core is started, it fills the system cache and verifies the database. The revealed inconsistencies in the
cached data are resolved automatically. However, the original data in the database remain corrupted and have to be
fixed manually. To do that, one may use the verifier log file.
The location of the said file is given by the log_file_v-erificator system parameter (by default,
/netup/log/verificator.log). For each item it contains:
– Description of the inconsistency, including its level (ERROR or WARNING);
– Supposed way to resolve the issue;
– SQL command (if required) equivalent to the automatic fix applied to the cached data:

-- WARNING slink 4876 exists only in dtagg_periodic

-- SQL DESC check slink exists and delete dtagg_periodic entry for deleted slink
UPDATE dtagg_periodic SET is_closed=1 WHERE slink_id=4876;

The objects listed in verificator.log as condemned to deletion are not loaded by the system and also
neither accounted for in the reports nor shown wherever in the administrator’s interface.

When applying the fixes to the database, it is desirable to stop the UTM5 core and create a backup copy of the entire
database, or at least of the tables affected by the fix.
In the trivial case all fixes may be applied by simply feeding the verifier log file into MySQL:

mysql UTM5 < /netup/utm5/log/verificator.log

However, some SQL queries in the log file are commented out, since they imply some (probably undesired) loss of data.
When dealing with such queries, one has to check every individual issue separately.

Archiving of tables
Some of the fastest-growing data tables may be archived in order to reduce the overhead expenses on insert
operations. An archiving implies that the table in question is renamed into an archive table, while an empty table with
the original name and structure is created to store the incoming data. Archiving may be done periodically. The
limitations are listed below.


201
Archiving of tables 

Currently the following tables are being archived:

TableTypeDate field name

discount_transactions_al 1 discount_date
l
discount_transactions_ 2 discount_date
iptraffic_all
tel_sessions_log 3 recv_date
tel_sessions_detail 4
dhs_sessions_log 5 recv_date
dhs_sessions_detail 6
payment_transactions 7 payment_enter_date
user_log 8 date
dhcp_leases_log 9 updated
invoices 10 invoice_date
invoice_entry 11
invoice_entry_details 12

In order to archive these tables:

1. Use the administrator’s interface to connect to UTM5
2. Go to the Archive DB page in Settings group of pages

3. Press in the upper part of the page to create an archive

One can do archiving once in 28 days. If button is not active, this means that less than 28 days passed
since the last archive was created.
Should you need to do the archiving more often, than is allowed by the administrator’s interface, please use the
db_archiver utility (see db_archiver utility on page 206)


202
NetFlow statistics generator 

Auxiliary utilities 29
NetFlow statistics generator
To emulate activity of users and export statistics via NetFlow v.5 protocol there is a utility called utm5_flowgen which
is installed to /netup/utm5/bin/utm5_flowgen. It may accept the following command line parameters:

–h IP address of the host to send generated NetFlow packets to. Default value is 127.0.0.1
–p Port to send generated NetFlow packets to. Default value is 9996
–c Number of NetFlow records. Default value is 65535
–v NetFlow protocol version. Supports versions 5 and 9
-f Name of a file which will be used as the source of data for sending. The default source is /dev/random/
Only for NetFlow version 5
-t NetFlow packets send rate.
-s Sender IP address in the NetFlow record.
-d Destination IP address in the NetFlow record.
-z Traffic source port in the NetFlow record.
-x Traffic destination port in the NetFlow record.
-n Traffic source AS in the NetFlow record.
-m Traffic destination AS in the NetFlow record.
-i Incoming traffic index in the NetFlow record.
-o Outgoing traffic index in the NetFlow record.
-b Number of transmitted bytes in the NetFlow record.
-P Number of transmitted packets in the NetFlow record.
-j TOS in the NetFlow record.
-k TCP flags in the NetFlow record.
-l Protocol ID in the NetFlow record. E.g. 6=TCP, 17=UDP, etc.
–N Next router IP address in the NetFlow record
–u Use a *.utm file as a source for the detailed NetFlow statistics

The following example command generates one NetFlow packet describing 1048576 bytes of traffic transmitted from
10.0.0.1 to 10.0.0.2:

/netup/utm5/bin/utm5_flowgen -c 1 -s 10.0.0.1 -d 10.0.0.2 -b 1048576

RADIUS statistics generator

For emulation of user activity and export of statistics via RADIUS protocol there is a utility called utm5_radgen which
is installed to /netup/utm5/bin/utm5_radgen. It may accept the following command line parameters:

–p Port for generated RADUIS packets to be sent to

–h IP address for generated RADIUS packets to be sent to
–s Secret word for communicating with RADIUS server
–c RADIUS packet code. Default value is 1 (Access-Request)
–i RADIUS packet ID. Default value is 1


203
get_nf_direct utility 

–u User password in public form. The value is sent with attribute ID equal to 2 (Password)
-a Attribute values
-b Binary attribute values in HEX ASCII
-q Quick mode: don’t wait for reply
-f Name of a file to read the authenticator from. By default, /dev/random
-v Display utility version

It is possible to set multiple attributes in a string of the following format:

vendor_id:attr_id:is_digit:value

Fields are separated by colons. In the first field the vendor identifier is set. Default value is 0.
The second field contains attribute identifier.
The third field is used to set data type, i.e. numeric or char. If the value is 0 then the data is transmitted as a character
string. If the value is 1 then values are transmitted as digits (integer).
The 4th field is used for transmission of the value itself.
Examples
1. To send an authorization request (Access-request) run the following command: 

/netup/utm5/bin/utm5_radgen -h 127.0.0.1 -p 1812 -s secret -u password -a 0:1:0:username

A RADIUS authorization packet will be generated for a user username with password: password.
2. To send a request for accounting (Accounting-request) run the command: 

/netup/utm5/bin/utm5_radgen -h 127.0.0.1 -p 1813 -s secret -a 0:1:0:username -a 0:40:1:1 -a

0:44:0:sessionid1 -c 4

A RADIUS packet will be generated with the accounting request for a user username stating that a session
started. with identifier sessionid1 is being started.
3. To send a request for accounting (Accounting-request) run the command: 

/netup/utm5/bin/utm5_radgen -h 127.0.0.1 -p 1813 -s secret -a 0:1:0:username -a 0:32:0:lo-

calhost -a 0:40:1:2 -a 0:44:0:sessionid1 -a 0:46:1:100 -c 4

A RADIUS packet will be generated with the accounting request for a user username stating that the session
stopped with identifier sessionid1 is being started. Session duration (Acct-Session-Time) is 100 seconds.

get_nf_direct utility
The get_nf_direct utility is designed to form detailed traffic reports based on the saved raw information.
The executable file is called /netup/utm5/bin/get_nf_direct.
It may accept the following command line parameters:

-D <dir> Path to directory containing the primary traffic information files

-b <database Name of file with primary traffic information
filename>
-a Account ID for the report
-s <source Traffic source ID for the report
address>
-d Traffic destination ID for the report
<destination
address>


204
utm5_payment_tool utility 

-p <source Source port for the report

port>
-P Destination port for the report
<destination
port>
-c <<t_class> Traffic class for the report
-f <from Time (Unix timestamp) to create the report since
t-imestamp>
-t <to Time (Unix timestamp) to create the report till (if not set, current time is used)
time-stamp>
-l <limit> Maximum number of lines in the report (unlimited by default)
-e Represent extended statistics
-C CSV format output
-h Version and usage info

utm5_payment_tool utility
The utm5_payment_tool utility is intended for making payments to a customer's personal account using third party
software.
Launch utm5_payment_tool with the following command:

/netup/utm5/bin/utm5_payment_tool

Each command line parameter consists of the space-separated key-value pair. The complete list of command line keys
and config file parameters is given below.
All string values must be passed in UTF-8 encoding.
Order of parameters is not important.

Configuration file
utm5_payment_tool uses the config file /n-etup/utm5/utm5_payment_tool.cfg.
Config file has the following format:

parameter=value

A sequence of symbols before the equals sign is treated as parameter’s name, while the one after it stands for the
parameter’s value. Whitespaces count. Empty lines are ignored. Any line starting with # is considered a comment.
All parameters may be passed to the program via the command line as well. The config file parameters have priority
over those given in the command line.
The list of available parameters and command line keys is given below:

Key Parameter Default value Description

-h <IP-адрес> core_host 127.0.0.1 IP address of the UTM5 core host.
-P <порт> core_port 11758 Is the port that UTM5 core uses to listen to URFA.
-l core_user init UTM5 core access login. By default, init.
-p core_password init UTM5 core access password. By default, init.
-k user_comment not set Comment for user Quoted string.
-L admin_comment not set Comment for administrator Quoted string.


205
db_archiver utility 

Key Parameter Default value Description

-c currency_id 810 Payment currency ID By default, 810.
-m payment_method 0 Payment method ID By default, 0.
-i turn_on_internet no Enable internet access after commiting the
payment By default, no.
-e accoun_id not set External payment ID Not set by default.
-a external_number not set User account number.
-b payment 0.0 Payment amount By default, 0.0.

db_archiver utility
db_archiver is used when updating UTM5. It allows one to compare the current DB structure with the one needed by
the updated UTM5 core. It allows one to update the DB structure and to archive tables that are meant to be archived.
The executable file is /netup/utm5/bin/db_archiver.
It may accept the following command line parameters:

–a Archive tables that are meant to be archived

–c <path> UTM5 configuration file path.
By default: /netup/utm5/utm5.cfg
–d Write the difference between the current DB structure and the DB structure, required by the new
UTM5 core to the log file
–e Update only those columns that have changed since the previous release and are marked for
update by NetUP
–f Update all columns whose format is different from the format, required by the new version of the
UTM5 core
–g Update the structure of tables meant for archiving
–i Update indexes
–n For MySQL do not consider a primary key without a default value a difference. For PostgreSQL
do not consider a primary key with NOT NULL constraint a difference
–t Verify archived tables
–l Temporarily prevent the UTM5 core from writing to the DB. This is required when archiving
tables without stopping the core. Use this option together with -a when the core is running
–q Turn off confirmations and minimize the output to log file. This may be useful when running this
utility on a schedule
–u Update the DB structure. This parameter is used together with the following parameters -e, -f,
-g and -i. E.g. -uef
-v Write the new DB structure description to the log file
-x <login> Login for communicating with the UTM5 core via the URFA protocol
-y <password> Password required for communicating with the UTM5 core via the URFA protocol. Both login
and password may be required if for some reason they differ from the ones in the UTM5
configuration file
–?, –h Show this help


206
Approaches to traffic shaping 

Appendix 30
Approaches to traffic shaping
Shaping is a limitation of bandwidth for IP traffic customers. The limitation may be of the following types:
– static (constant, defined solely by the tariff plan);
– dynamic (may depend on time and on the amount of traffic consumed).
UTM5 provides interface for setting up both static and dynamic shaping for selected services and tariff plans.
Actual bandwidth regulation occurs on the traffic routers, which may be PC-routers, Cisco routers, etc. The billing
software may interact with those in following manners:
1. Using external scripts. On some external event (say, when the traffic exceeds some threshold) the billing system
starts an external script controlling the shaper to change the bandwidth or probably break the connection. The user’s
IP address and the new bandwidth may be passed to the script as parameters.
The script calls external traffic control utilities (for example, tc from the iproute2 package for Linux, or ipfw for
FreeBSD with enabled dummynet). Usage of these utilities may require additional tuning of the OS and/or other
software.
1. Using RADIUS attributes (for VPN and dialup services). A response given by the RADIUS server to an authentication
request may include one or several attributes controlling the connection bandwidth for the given user on the given
NAS, if the NAS supports this functionality. Cisco routers are an example of such NAS.
In this way the bandwidth is set for a connection permanently as it is established, so any corrections will have to wait
till the next connection.
These two methods may be used either simultaneously as well as separately.
UTM5 uses the following approaches to shaping:
1. In case of shaping by the external scripts, the parameters to pass to the script are set up on the Firewall rules page
(see Administrator’s interface: Firewall rules on page 70for more expanded description of RFW workflow and for
interface details). Each rule is associated with one or several events that trigger the script with the prescribed
parameters. Path to the script is set via the firewall_path variable in the utm5_rfw.cfg config file.
– Static shaping may be done by the rules linked to the Internet on event.
– Dynamic shaping is possible in case if the corresponding module is present, and is set up by the rules linked to
the events Set bandwidth limit, Edit bandwidth limit and Delete bandwidth limit on incoming or outgoing
channel. Events of the first two kinds occur when the traffic amount passes over some predefined borders, and
the Delete bandwidth limit happens at the end of accounting period or when a service link is deleted. The borders
can be made time-dependent, so that the switch of time ranges may also fire the events of these types. See
Administrator’s interface: Dynamic shaping on page 77.

The dynamic shaping module requires a separate license.

2. In case of RADIUS attributes-driven shaping:

– Static shaping is set up on the RADIUS Parameters tab on Service page in the Tariffication group (see
Administrator’s interface: Services on page 48).
– Dynamic shaping is possible in case if the corresponding module is present, and is set up on the RADIUS
parameters tab of the Dynamic shaping page under Settings (see Administrator’s interface: Dynamic
shaping on page 77). Certain RADIUS attributes may be provided for each service in order to limit the bandwidth
depending on the traffic amount. Dynamic adjustment of attributes is enabled by the use of variables.

RADIUS parameters
Below is an example of RADIUS attribute for dynamic shaping to use with Cisco router.


207
Approaches to traffic shaping 

– Vendor – is set to 9;
– Attribute – is set to 1;
– Attribute type – is set to string;
– Value –

is set to lcp:interface-config#1=rate-limit input IN_BANDWIDTH_BITS

IN_CISCO_NORMAL_BURST IN_CISCO_EXTENDED_BURST
conform-action transmit exceed-action drop

Before sending this string to NAS, the system substitutes the IN_BANDWIDTH_BITS variable with the numeric value
of bandwidth for the given user (in bits/sec), determined from the current time and consumed traffic amount, as
prescribed by the shaping settings. The following two variables are interpreted as follows:
IN_CISCO_NORMAL_BURST is a number of bytes to send in one burst. It is calculated as the number of bytes passing
in 1.5 seconds at given bandwidth.
IN_CISCO_EXTENDED_BURST is the possible amount of bytes above burst size to send in one interval. If spent, it must
be compensated at the cost of bandwidth at periods when the load is below maximum. Its numeric value is twice larger
than the normal burst size.
The rest of instructions state that the traffic within the given bandwidth and the allowed excesses is to be passed
through (conform-action transmit), while the extra packets after the depletion of excess burst size are ignored
(exceed-action drop).

External scripts
The examples of executable files are presented below. It is supposed that the firewall rules for Set bandwidth limit, Edit
bandwidth limit, and Delete bandwidth limit are already created, and each of them lists the script parameters in the
following form:

UID UIP UBITS UMASK BANDWIDTH [0|1|2]

First five parameters are the variables to be replaced with their values on execution:

UID user ID
UIP user IP address
UMASK user network mask
UBITS binary network mask
BANDWIDTH current connection bandwidth

The last parameter is either 0, 1, or 2, depending on the nature of the event:

– 0 – Delete bandwidth limit;
– 1 – Set bandwidth limit;
– 2 – Edit bandwidth limit.

Linux
Below is the example for the iproute2 software shaper running on GNU/Linux.
It is assumed that the following commands have been run in advance:

tc qdisc add dev eth0 root handle 1: htb

– a queueing discipline (qdisc) with ID=1 is created on the incoming interface eth0. The simple and quick Hierarchy
Token Bucket (htb) method of ordering is set for the queue.

tc class add dev eth0 parent 1: classid 1:1 htb rate 100mbit ceil 100mbit burst 200k


208
Template variables 

tc class add dev eth0 parent 1:1 classid 1:10 htb rate 1mbit burst 20k

– a root class with ID 1:1, guaranteed bandwidth of 50 Mbit/sec (rate 50mbit), and peak bandwidth of 100
Mbit/sec when unoccupied bandwidth is available (ceil 100mbit), passed through in a 200 KB bursts (burst 200k)
is created for the queue. It will be used as the parent for all other classes and distribute the bandwidth among them
with the ability to borrow the unoccupied portion from each other. Besides that, a class with ID 1:10 is created with
bandwidth 1Mbit/sec without borrowing, to let through the unidentified traffic from the queue.

tc filter add dev eth0 parent 1: protocol ip prio 3 handle 1 fw classid 1:10

– a filter is created to direct the uncategorized traffic from the queue to the class with poor bandwidth.
Later on, when the script is called due to the Set bandwidth limit events, it works as follows:
– an iptables rule is created to mark the traffic packets incoming to the given IP address (outgoing traffic may be
shaped separately in a similar manner);
– a new filter is created sending the marked traffic into the new class;
– a new class is created with the given bandwidth.
On Edit bandwidth limit event the bandwidth of the class is altered, and on Delete bandwidth limit the class is deleted
together with the corresponding filter and the iptables rule.
The traffic to which no filters apply (i.e. belonging to the users for whom the shaping is not set up) skips the queue and
passes directly.
The script itself is given below:

#!/bin/bash if="eth1" echo $* echo "First create: tc qdisc add dev $if root handle 1: htb"
case "$6" in
0) iptables -t mangle -D FORWARD -s 0/0 -d $2/$3 -j MARK
--set-mark $1 tc filter del dev $if parent 1: protocol ip prio 3 handle $1 fw classid 1:$1
tc class del dev $if parent 1:1 classid 1:$1 htb rate $5kbit burst 20k;;
1) iptables -t mangle -A FORWARD -s 0/0 -d $2/$3 -j MARK
--set-mark $1 tc filter add dev $if parent 1: protocol ip prio 3 handle $1 fw classid 1:$1
tc class add dev $if parent 1:1 classid 1:$1 htb rate $5kbit burst 20k;;
2) tc class change dev $if parent 1:1 classid 1:$1 htb rate $5kbit burst 20k;; *) echo "Usage:
`basename $0` {UID UIP UBITS UMASK BANDWIDTH [0|1|2]}" >&2 exit 64;; esac

FreeBSD
Below is an example script for dummynet working on FreeBSD.
When the script is called on Set bandwidth limit, a pipe with limited bandwidth is created together with the rule that
directs the incoming traffic of certain user on the em0 interface to this pipe. On Edit bandwidth limit pipe bandwidth
is changed. On Delete bandwidth limit the pipe and the corresponding rule are deleted.
Script is designed to work in multipass regime (sysctl net.inet.ip.fw.one_pass must return 0).

#!/bin/sh case "$6" in 0) /sbin/ipfw delete $1 /sbin/ipfw pipe delete $1;; 1) /sbin/ipfw pipe
$1 config bw $5Kbit/s /sbin/ipfw add $1 pipe $1 ip from any to $2/$3 via em0;; 2) /sbin/ipfw
pipe $1 config bw $5Kbit/s;; esac

Template variables
This section contains the list of variables which may be used in templates of various types (see Document templates
on page HIDDEN).


209
Template variables 

Variables
Template variables are split into several groups:
– Document

Name Type Description

document.number int32 Document number
document.alt_number string Alternative document number
document.date int32 Document creation date

– User

Name Type Description

user.id int32 User ID
user.full_name string Full name of the user
user.login string User login name
user.password string User password
user.actual_address string Actual address
user.juridical_address string Legal address
user.home_telephone string Home phone
user.work_telephone string Work phone
user.mobile_telephone string Mobile phone
user.tax_number string ITIN
user.kpp_number string Reg. code
user.icq_number string ICQ number
user.web_page string Web page
user.district string District
user.building string Building
user.entrance string Entrance
user.floor string Floor
user.flat_number string Flat number
user.personal_manager string Personal manager
user.basic_account int32 Basic account ID
user.passport string Passport
user.email string E-mail
user.comments string Comments
user.bank_account string Bank account
user.bank_name string Bank name
user.bank_city string Bank city
user.bank_bic string BIN
user.bank_corr_account string Bank corr. account number
user.currency_short_name string Currency short name
user.currency_full_name string Currency full name


210
Template variables 

Name Type Description

user.currency_code int32 Currency code

user.params.{param_id} (a) string Additional user parameter with ID {param_id}

user.contacts.{contact_id}.email (b) string Additional contact e-mail with ID {contact_id}

user.contacts.{contact_id}.full_name string Additional contact full name with ID {contact_id}

user.contacts.{contact_id}.short_nam string Additional contact short name with ID {contact_id}
e
user.contacts.{contact_id}.position string Additional contact position with ID {contact_id}
user.contacts.{contact_id}.reason string Additional contact description with ID {contact_id}
user.contacts.{contact_id}.telephone string Additional contact phone number with ID {contact_id}

a. {param_id} is an integer value of the ID of an auxiliary user parameter

b. {contact_id} may take the following values: headman, booker (accountant) or an integer additional contact ID, starting with one

– Personal account

Name Type Description

account.account_id int32 Account ID
account.external_id string External account ID
account.balance double Balance
account.credit double Credit
account.vat_rate double VAT rate
account.sale_tax_rate double Tax rate
account.access_card_number string IPTV access card number

– Provider

Name Type Description

provider.full_name string Provider name
provider.short_name string Provider short name
provider.juridical_address string Legal address
provider.actual_address string Actual address
provider.tax_number string ITIN
provider.kpp_number string Reg. code
provider.chief_full_name string CEO
provider.chief_short_name string CEO: short name
provider.booker_full_name string Accountant name
provider.booker_short_name string Accountant: short name
provider.bank_account string Bank account
provider.bank_name string Bank name
provider.bank_city string Bank city
provider.bank_bic string BIN
provider.bank_corr_account string Corr. account number


211
Template variables 

– Contract

Name Type Description

contract.number int32 First contract ID
contract.name string First contract name
contract.date int32 First contract creation date

contract.{contract_id}.number (a) int32 ID of a contract # {contract_id}

contract.{contract_id}.name string Contract # {contract_id} name

contract.{contract_id}.date int32 Contract # {contract_id} date
user.connect_date int32 User connection date (format unixtime)
user.connect_date..date_short string User connection date (format DD.MM.YYYY)

a. {contract_id} is the user’s contract ID, starting with one

– Payment

Name Type Description

payment.id int32 Payment transaction ID
payment.amount_in_currency double Amount in used currency
payment.amount_absolute double Amount in system currency
payment.date.actual int32 Actual payment date (when it is registered by UTM5)
payment.date.enter int32 Payment date (when it was made by user)
payment.date.burn int32 Payment expire date
payment.document_number string Payment document number
payment.comments.user string Comments for user
payment.comments.admin string Comments for administrator
payment.hash string Payment hash
payment.currency_rate double Currency rate
payment.currency_short_name string Currency: short name
payment.currency_full_name string Currency: full name
payment.currency_code int32 Currency code

– Bill

Name Type Description

bill.sum_without_tax double Sum w/o taxes
bill.sum_with_tax double Sum, including taxes
bill.size int32 Number of lines in bill
bill.period_start int32 Period start date
bill.period_end int32 Period end date
bill.balance_when_created double Balance at the moment when bill was created
bill.debt double Debt
bill.payment_amount double Payment amount w/o taxes
bill.payment_amount_with_tax double Payment amount with taxes
bill.date int32 Date


212
Template variables 

– Call details

Name Type Description

summary.periodic_fee double Periodic service fees
summary.total_fee double Telephony service fees
summary.other_fee double Other services fees
summary.local.charges double Local call charges
summary.local.count double Local calls number
summary.local.duration double Local calls duration
summary.innerzone.charges double Same for inner zone calls
summary.innerzone.count double
summary.innerzone.duration double
summary.intercity.charges double Same for intercity calls
summary.intercity.count double
summary.intercity.duration double
summary.international.charges double Same for international calls
summary.international.count double
summary.international.duration double

– IPTV service links

Name Type Description

iptv.access_card_number int32 IPTV access card number
iptv.activation_code.part1 string Access card activation code, part 1. Activation code consists of
six parts. For each part there is a corresponding variable with a
different number at the end of it's name (.part2,.part3, etc.)

Iterating variables
This section contains the list of iterating variables. When generating a document, these variables are replaced with an
array of values. They should be placed in a table row in a document template. In this case the number of rows in the
table is automatically increased to hold all the values that are returned.
Iterating variables also are split into several groups:
– IP group table iterators

Name Type Description

ipgroup.login string IP group login
ipgroup.password string IP group name
ipgroup.mac string MAC address
ipgroup.ip string IP address
ipgroup.mask string Subnet mask
ipgroup.gateway string Gateway

IP group table iterators only include non dynamically created IP groups that have a non empty Login field and
a non zero IP address


213
Template variables 

– Connected tariff plans table iterators

Name Type Description

tariff.name string Plan name
tariff.cost double Cost
tariff.account_id int32 Personal account ID

– Bill iterators

Name Type Description

bill_entry.id int32 Entry index, starting with one
bill_entry.name string Entry name
bill_entry.price double Entry price
bill_entry.quantity double Quantity
bill_entry.sum_with_tax double Sum, including taxes
bill_entry.sum_without_tax double Sum w/o taxes
bill_entry.tax double Tax
bill_entry.tax_rate double Tax rate
bill_entry.unit_name string Unit name (returns replacement key)
bill_entry.unit_code string Unit code (returns replacement key)
bill_entry.alt.price double Alternative price
bill_entry.alt.quantity double Alternative amount
bill_entry.alt.unit_name string Alternative unit name (returns replacement key)
bill_entry.alt.unit_code string Alternative unit code (returns replacement key)

– Call details iterators

Name Type Description

call.id int32 Call ID
call.zone string Zone name
call.direction string Direction name
call.date int32 Call date
call.calling_number string Calling number
call.called_number string Called number
call.called_prefix string Called prefix
call.duration int32 Call duration
call.type string Call type (returns replacement key)
call.cost double Call cost

– Iterators of service link parameters for dialup service

Name Type Description

dialup.login string Login name
dialup.password string Password
dialup.cid string CID parameter value


214
Template variables 

Name Type Description

dialup.csid string CSID parameter value

– Iterators of service link parameters for hotspot service

Name Type Description

hotspot.login string Login name
hotspot.password string Password

– Iterators of service link parameters for telephony service

Name Type Description

telephony.login string Login name
telephony.password string Password
telephony.number string Telephone number
telephony.incoming_trunk string Incoming trunk
telephony.outgoing_trunk string Outgoing trunk
telephony.pbx string PBX ID parameter value
telephony.cid string CID parameter value

Template types
Depending on the template type, it may include variables from the following groups:
Commercial invoice

Print receipt
User memo

Call details
Certificate

Contract
Bill

Document • • • • • • •
User • • • • • • •
Personal account • • • • • • •
Provider • • • • • • •
Contract • • • • • • •
Payment •
Bill • • •
Call details •
IPTV service links • •
Bill iterators • • •
IP group table iterators • •
Connected tariff plans table iterators • •
Call details iterators •


215
Template variables 

Variable modifiers
Variable modifiers modify the values returned for variables. The following modifier types are available:

Name Argument Result type Description

type
translate string string Replaces with a value from the replacements list if the
variable and the key match (a)
replace string string Replaces matching part of the variable with the value from
the replacements list
date_short int32 string Date format DD/MM/YYYY
date_long int32 string Date format “DD” Month YYYY
date_time int32 string Time format MM.DD HH:MM
duration int32 string Duration format HH:MM:SS
sum_to_string double string Sum to string

a. See Administrator’s interface: Replacements in documents on page 76

In order to use a variable modifier, add its name after the name of a variable, separated by two dots:

Then insert the modified variable into the template.


216
Phone: +7 495 510 1025
Fax: +7 499 783 0080
Address: Russia, Moscow, Ulofa Palme str. 1, sect. 7
Post: 119311, Russia, Moscow, P.O. Box #87
E-mail: info@utm-billing.com
Web: http://www.utm-billing.com

© NetUP Inc. All rights reserved. March 6, 2019