Course13:IT Connect - 11.0 The individual Device User Interface

From innovaphone wiki
Jump to navigation Jump to search

The full device admin UI.

What it is

As you have seen in the training, the complete telephony system is a rather complex system consisting of various components:
  • the PBX runs on one of your gateways (the IP411LEFT in this case)
    it is responsible for basic telephony functions such as registering phones and interfaces (SIP, FXS, ISDN, ...) and for the call handling

  • the Apps Platform runs on the same gateway (the IP411LEFT) but on a separate processor
    here, various applications (such as Fax, Devices, UsersAdmin etc.) run

  • the myApps client running on your computer (either in your browser or in the myApps launcher)
    it provides an universal environment for all the user interfaces we have used so far

  • gateways (such as the IP811) which provide additional interfaces and fax or conferencing resources

  • and of course the phones (hardware phone such as the IP112 or the phone apps)
When we were using the administrative tools during the training, we didn't really care about this. Whatever we did, we just did it from within the same myApps client using the same administrative Apps. This is because the administrative Apps know the details about the internal structure of your system and do "the right thing" for you.

Sometimes however, when you want to go in to more depth than what the administrative Apps in myApps allow you to do, you need to bypass the Apps and configure the devices directly. Because this user interface provides access to just every feature available in our boxes, it is also known as advanced UI.

How to access


Each device has an individual administrative web user interface which can be accessed directly using an URL like http://ip-address-of-device.

You can try that out right away. For example, to access your training router's (IP411right) user interface, use http://172.31.31.1/admin.xml?xsl=admin.xsl.

However, when you try it, you will immediately run in to the first problem: you will need an account on each device. Of course, you could create an account on each device and also, you could keep the passwords for all these accounts in-sync. But that's tedious obviously. And insecure (imagine your password gets known to someone and you have to change it on all devices)!

Also, in many projects, some of the devices are not reachable at all directly via IP. Think of a situation where a customer of yours has some phones or gateways in a remote location behind a firewall or NAT router. Unless you have a VPN installed, there is no way to access such devices.

These are the reasons why you don't do it this way.

Using devices

Instead, you use the Devices App. You might recall screenshot.png a section in the device related functions called Admin UI.

As soon as you have access to the Devices App, you have instant single-sign-on access to all of the individual admin user interfaces of all devices that have been added to Devices.

So how can Devices access those devices if you can't? And is this secure?

When you add a device to your system, the URL of your App Platform will be screenshot.png configured to the device. When the device starts up, one of the first things it does is to establish a connection to your Devices App.

Also, a random shared secret will be negotiated between the device and your Devices App. This makes sure that no man-in-the-middle could fool your device in to thinking it connects to your Devices App when it does not.

The Devices App in turn only starts up when you are authenticated to the system and the App has been made available to you.

When a device has established a connection to your Devices App, all web UI request will be sent to the App first and from there to your device. This is possible because the connection to the device is not established by you (nor by the Devices App) but by the device itself to Devices. As long as the system is set up so that all devices (and you) can connect to Devices, your access to the devices admin UIs will work. This is usually made possible by using a Reverse Proxy (which we have looked at before in this course).

What the Install does

To get used to the administrational web UI of the devices, we will not explain all the options in detail. This would take a while (believe me, a real while) and also, it is not necessary for you. Instead, we will have a look at what the Install did and how it looks in this UI.

We will start with the PBX. So to see the Admin UI of the PBX
  • open Devices
  • select the Devices tab on the upper left
  • click on PBX - hq.dvl-ckl2.net
  • select the Admin UI section on the right side
You will now screenshot.png see the Admin UI in the right half of the Devices window.

(Further Hints) Using the screenshot.png two little buttons on the upper right you can enlarge the Admin UI part of the Devices window or you can even create a separate window with the Admin UI only. This is quite neat, especially on smaller displays.

IP

One of the first things the Install was asking you is about IP settings of your PBX. You'll find them in screenshot.png IP4/ETH0 (these are the IP settings for the first Ethernet interface, you know, nerds always count from 0 wink).

Your IP411 has 2 Ethernet interfaces (ETH0 and ETH1) but the second one is rarely used.

What you don't find here is the domain name you specified for the PBX (hq.dvl-ckl2.net). You'll see that in screenshot.png PBX/Config/General.

PBX base data

When you switch to screenshot.png PBX/Config/General, you see that the Install has set the System Name (your domain name, dvl-ckl2.net), the PBX Name (hq) and the PBX's full domain name DNS (hq.dvl-ckl2.net).

The Response Timeout has been set to 15. This is the time after which a CFNR is executed.

The Group Default Visibility defines the visibility that is assumed if users share the same group as discussed when we talked about group pickup before.

The Log Calls check-mark is ticked, so you can see live-loggings of calls in the Logging App.

Reverse Lookup

An interesting entry is also made for the Reverse Lookup URL: ldaps://apps.dvl-ckl2.net/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=dvl-ckl2.net\contacts

When the PBX forwards a call which does not contain name information for the calling side, it performs a so-called reverse lookup. That is, it tries to find a directory entry that matches the calling party number and then adds the resulting name information to the call so that it can be displayed on the phones and/or in myApps.

The reverse lookup is done using the LDAP protocol towards an LDAP directory service. You already guessed it: in our case this directory service of course is our Contacts instance. The service to be used is determined by the aforementioned lookup URL. Let's look at the components:
  • it has an LDAP scheme (ldap://)
  • the host is our App platform (apps.dvl-ckl2.net)
  • the remainder of the URL are the details of the LDAP query. No need to understand all their parts except for the bindname parameter (bindname=dvl-ckl2.net\contacts). This is the user to login with at our Contacts instance
The password is the App service instance's password as set in the App manager (in our training case, it would be ip411, generally it is the random and strong password created by the Install).

Two factor authentication

In screenshot.png PBX/Config/Authentication the Install has ticked the Two factor authentication check-mark (if you have ticked it yourself during the setup).

Call Filter

Some call filters have been set in screenshot.png PBX/Config/Filter.

You can add more filters or change the existing ones, although it should be rarely necessary.

The thing to understand is that a filter is made up of a list of rules which are executed from top to bottom. If the Number matches, Next is evaluated:
  • if its nok, the call is denied
  • it is ok, the call is allowed
  • if its neither, the next rule is examined

PBX Objects

The most interesting part of all is the screenshot.png PBX/Objects section for sure.

Most of the functions of the PBX are implemented by objects. The most obvious type of object of course is a User. But the are many more and we'll do a quick walkthrough in the next sub-chapters.

Before we do this, let's have a look at the columns in the list:

  • the Long Name is a descriptive name for the object.
    It has to be unique throughout the system. For a user object, this is something like Christoph Künkel. In fact, the Long Name of a user is what is called the ID in UsersAdmin

  • a Name also is unique in the system.
    It is usually shorter than the Long Name and can be used to call to an object. It might look like ckl and is often identical to the user-part of a user's E-Mail address (i.e. what is in front of the @). In UsersAdmin this is called Username

  • No is the Extension in UsersAdmin, so it is a unique number which may be used to call

  • HW-ID is a unique identifier for an endpoint that may register with an object to place and receive calls (for example a telephone used by a user.
    You should normally not change these values here, rather use the provisioning mechanism described before

  • Node and PBX are advanced stuff wink
    in the installations covered in this course, you never change them

  • Filter is the call filter assigned to an object. For user objects, it is normally overridden by the Filter property of the Template assigned to the user

  • Groups is a simple list of groups assigned to an object

  • CF lists the call forwards set for an object

  • Fork shows the mobility settings for a user
    (ok, you don't know what that is for now, we'll coma back to it in a minute)

  • Config is the name of the template used by the object

  • in the Visibility settings, the object's privacy filters are stored

  • Rights define the access rights a user has when using the PBX's individual web user interface
    In the scope of this course, it is not used

  • the Type of an object defines what it actually does
    Some popular types are
    • User - a user wink
    • Executive - also a user but with some special behavior (not covered in this course)
    • Waiting Queue - this is what you configure in the Waiting Queues PbxManager plugin
    • Voicemail - a voice mail as configured with the AP Voicemail <language> PbxManager plugin
    • Messages - a message store used for persistent messaging
    • PBX - each physical PBX has a PBX type object
    • Fax - a fax server as configured by the AP Fax PbxManager plugin
    • Config Template - a template as configured by the Templates PbxManager plugin
    • Boolean - a time switch as configured by the Time switches PbxManager plugin
    • App - an App which is available in the myApps client
    • AP - an App Platform

  • Presence
    the current presence-state and -note for an object

  • Wakeup
    a very special property not handled in this course
When the Type column is empty, the object is of type User.

By the way: whenever you need more information about an object or any other page in this UI, there is a screenshot.png help link towards innovaphone's wiki.

PBX Objects - Users

Christoph Künkel, Jean Dupont, Lisa Svensson and Mario Rossi are user objects of course. When in normal operation there is no need to modify any of these objects here, always use UsersAdmin instead.

Apps and Licenses



One of the notable exceptions from this rule is when you need to assign Apps or licenses to individual users (as opposed to configure them in a template). In this case, after clicking on the Long Name, you can switch to the screenshot.png License and App tabs and assign them individually. These setting add to those set forth in the template.

However, whenever possible, use templates and the Templates PbxManager plugin to assign Apps and licenses.

Phone

The other notable exceptions is the configuration of phones, function keys in particular. We have seen how function keys can be defined in the Templates PbxManager plugin. But this is only a very limited subset of all the options you have.

If you click in to screenshot.png the Phone column of an user object (which either shows a + if there is no special config yet for the user or the word config otherwise), a pop-up window will open that gives you a lot of configuration options. However, from all the items on the left menu-bar, you should only look at Preferences and Function keys.

As said before, there are help pages available in the innovaphone wiki:




PBX Objects - Templates

Like the users you configured in UsersAdmin are stored in user objects on the PBX, the templates configured with the Templates PbxManager plugin are stored in template objects on the PBX. The Install has created two of them as you know, Config User and Config Admin.

Again, the same is true as said before for the user objects: you usually do not touch the template objects in the PBX, rather use the Templates PbxManager always.

More function key types



Of course, there are some notable exception: like for the users, you can define much more sophisticated function keys for a template. Function keys defined in a template are inherited by all phones of users who have the respective template assigned.

Here is the wiki page for the function keys again (it is actually identical to the page for users we discussed in the previous chapter): fish-help.png Phone/User/Function-Keys

Setting the phone UI language

The template created by the Install sets the phone language to English. In a real-life project you probably will want to change this default language. You can do this by editing the Config User template. video2.png Open the phone configuration (by clicking on the word config in the Phone column), switch to Preferences and select the desired Language.

PBX Objects - Waiting Queue

You already guessed it - waiting queues you created with the Waiting Queues PbxManager plugin are stored in objects of type Waiting Queue in the PBX.

The plugin does whatever it takes to create an common scenario. In the Advanced Training we will talk about additional features of the waiting queue that might be helpful but are only necessary in special scenarios. These options can be set through the Advanced UI.


PBX Object - Trunk Line

The trunk line which we have created in the Trunks PbxManager plugin is stored in two places. First, an object of type Trunk Line is created in the PBX. This obect basically stores the trunk access number (as Number in the main data) and the various forwarding destinations as screenshot.png Loopback etc. in the Trunk tab of the main data.

The more interesting part however is in screenshot.png Gateway/SIP/SIPx. Sometimes, for example if you run in to interop issues with your SIP provider, the innovaphone support may ask you to do some changes here.

Maintenance

Probably one of the most important pages in the device user interface. Four of the sub-pages are relevant.

Logging

The Install has configured all your devices to send alarm, event and log messages to the Events App on your App platform (more precisely, it has created a Device configuration of type Alarm server in Devices that does so. This can be found in screenshot.png Services/Logging). When you look at Maintenance/Logging you see that it also has screenshot.png ticked some of the check-marks (PBX Calls, Gateway Calls and H.323 Registrations). This is the reason why you see log messages in the Logging App when a call is done in the PBX (or endpoints register/deregister).

This is a good tool to understand what is happening on your system and you may want to tick or untick some log level types.

One more nice real-time logging tool is available in screenshot.png PBX/Calls. This lists all current calls in the PBX and is always available (no need to enable it).

Tracing

Sometimes, you need to dig really deep in to the internals of what is happening in your system. One of the most valuable tools you can use then is known as tracing. You obtain trace files from a particular device with an open source tool called WireShark (see fish-help.png Pcap for details).

The adventurous among us can of course try it out for themselves. However, in most cases, you will be instructed by the innovaphone support staff to obtain traces. They will tell you which particular trace flags to set here. As a rule of thumb, you should screenshot.png always tick at least All IPv4 TCP/UDP Traffic, All IPv4 TLS Traffic and Enable RPCAP. You will then save the captured trace to a file and send it to innovaphone.

(Further Hints) Make absolutely sure that you turn off Enable RPCAP when you're done with tracing. Leaving it enabled is a securiy risk!

Ping & Traceroute

These provide the well-known ping and traceroute (or tracert for the window-ishs of us) functions. Note that the function is executed on the remote device, so you can for example ping within a customer network although you might not have access to this network.

Uploading Licenses

As we have dicsussed before (in the Using Templates book), licenses need to be
  • purchased
  • bound to your PBX device
  • uploaded to your PBX device
  • and assigned to individual users (either directly or via templates)
The first two steps are done using the my.innovaphone utility and there is a nice tuorial about how this works available in link_intern.png www.innovaphone.com: myTutorial. In the end, you would download a license file that can then be uploaded to your PBX (the third step). This is done using the web administration UI of your PBX at screenshot.png General/License.

A license guideline detailing which licenses are available and how they work is available as link_intern.png innovaphone Licensing Guidelines V13r2 on innovaphone's web site (note: at the time of this writing, Jan 2023, there was no 13r3 licensing guide available. At the time you are reading this, there might be one though).

Loading licenses directly from my.innovaphone

If your device has internet access, you can also transfer the licenses directly from my.innovaphone to the device without first downloading it to your PC. This is done using the screenshot.png my.innovaphone.com link in General/License. You need to screenshot.png provide and save your my.innovaphone account and can then have the device download the licenses directly.

We recommend to remove the account data afterwards in order to avoid malicious license manipulation.

myApps settings

As we have discussed in the Managing Devices book, myApps can update itself when a firmware update of the PBX is done.

Here is how this works in a bit more detail:
  • when Devices succeeds to update the firmware of a PBX, it will screenshot.png note both the build number and the App Store URL in PBX/Config/myApps
  • this is done before the PBX is restarted to activate the new firmware
  • when the PBX restarts, all myApps clients are disconnected and will try to reconnect soon
  • upon a fresh connection to the PBX, the current build is compared to the build noted in the PBX
  • if it does not match, myApps (more precisely: the innovaphonemyAppsUpdateService installed along with the native myApps client) retrieves the screenshot.png file software.json from the URL set as App store URL
  • if there is a matching version noted in this file, this version is retrieved and installed

Client settings

Various options of the myApps client screenshot.png can be set by the administrator. Each of these options can be used to change the default settings according to the administrator's wishes. If the Force checkmark is enabled, the user will not be able to override the administrative settings.

Those options are described in fish-help.png the zip file at the bottom of this page. Since the PBX already knows the DNS name and the required URLs, the file is already pre-configured for your system.

Options in a PBX object's Devices list

When a device (i.e. phone) is associated to a user, an screenshot.png entry in the Devices list of the user is created and can be seen and edited in UsersAdmin.

We did not look at those in detail as the provisioning mechanism just does it right for you. However, sometimes it is useful to know what's in those entries:
  • Hardware id
    This is the unique identifier for the device. This is for example the serial number of the device for a phone (e.g. 009033300dad) or the serial number of the gateway followed by an interface name for an analogue phone (e.g. 0090334000b3-TEL1)

  • Name
    The nickname which is displayed to the user for the device (which does not need to be unique, e.g. hq IP Phone IP232)

  • App
    The default phone App to be used with device

  • PBX Pwd
    If set, registrations can be done using the PBX password instead of the user's password. Rarely used

  • No IP Filter
    If set, the screenshot.png registration filters (as defined in PBX / Config / Filter) are not applied for this user

  • TLS only
    If set, registrations with password are not allowed. Instead, only registrations with a valid certificate provided by the registering device are allowed

  • No mobility
    If set and there is a current registration for this device, then mobility (additional forwarding calls to your mobile phone) is disabled. This makes a lot of sense for the softphone used on your myApps for iOS/Android

  • Reverse Proxy
    If set, registrations are allowed through the revere proxy too (otherwise, they are rejected)
The Reverse Proxy setting works by comparing the IP source address of the registration request against the IP address of the reverse proxy (which is known to the PBX as screenshot.png PBX/Config/General/Reverse Proxy Addresses.


Allowing registrations from devices with no valid certificate

When the system sets up a registration for a telephone or an interface, it will configure it so that the registering endpoint is authenticated using its built-in certificate. This is done by screenshot.png setting the TLS only check-mark in the user's Devices list entry.

In most of the cases, you just don't need to worry. The device will have a valid certificate and the PBX will know which certificates are trustworthy (this by the way is controlled by the screenshot.png Trust list in General/Certficates). However, there are a few situations where this doesn't work.

As you might know, there is an innovaphone product called IPVA which is a virtualized gateway (including a PBX). This is a software only solution and runs on VMware or Hyper-V. As such, it obviously has no secure, trustworthy and built-in certificate. When this IPVA is configured for example as an SBC to connect to your SIP provider, its registration to the PBX will fail therefore.

There are two possible solution to this:
  • turn off the TLS only flag on the Devices entry of the respective Trunk line on the PBX. Also, both on the trunk line and the SIP interface on the IPVA, a password must be set instead. Although this works, the PBX Manager will overwrite these settings whenever you reconfigure the trunk unfortunately

  • therefore, the second option is better: you need to have the PBX trust the SBC's self-signed certificate. Generally, innovaphone devices trust only certificates whose certificate (or one of their root certificate) is listed in the Trust list section of General/Certificates. You can import the certificate to be trusted using the screenshot.png Upload button in the Trust list area. The certificate file (either PEM or DER format) can be download from the calling device in using the screenshot.png PEM or DER download link in the Device certificate section of General/Certificates.

Turning off the DNS-less mode

We have discussed the DNS-less mode in the Lesson on Setting up the basic System before. Here is how to screenshot.png turn it off:
  • open the PBX's advanced UI
  • select PBX/Config/General
  • remove the DNS and IP entries in the IP address for App Platform section
  • turn off the Operation without DNS check-mark
  • click on OK to save the configuration

Please note that you should never change the screenshot.png DNS entry in the PBX Name section however, as this results in an inconsistent configuration. This is because the DNS name appears in a number of settings throughout the PBX which makes it difficult to change.