Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update

From innovaphone wiki
Revision as of 11:32, 17 September 2018 by Ralston-Hilse (talk | contribs)
Jump to navigation Jump to search

Applies To

This information applies to

  • all innovaphone Devices Version 7 and up


More Information

Problem Details

When the configuration of an innovaphone device shall be changed programmatically, there are generally two options

  • apply changes using the config change/add/rem commands
this is the recommended method for each configuration change that actually can be effected like so. However, some changes cannot be done this way, so the second alternative can be used
  • apply changes by mimicking the administration UI
this article is about this second alternative. All changes which can be applied using the administrational UI can be also effected this way.


Configuration

Each edit done with the administrational UI is finally translated into a an HTTP GET request with appropriate query args, this in turn is translated internally in to an equivalent mod cmd call. To learn how the request needs to look like, you would

  • tick the Administration check-mark in the Maintenance/Logging tab
  • perform the change you need to effect using the admin UI
  • obtain log

Let us assume, you want to modify the User-3 registration of a phone. In the log, you will find something like

20130312-142901 CMD admin@172.16.68.130 mod cmd PHONE/USER-UI reg-edit-reg /redirect http%3A%2F%2F172.16.68.128%2FPHONE%2FUSER-UI%2Fmod_cmd.xml%3Fxsl%3Dreg_edit_reg.xsl%26cmd%3Dreg-edit-reg%26id%3D2%26op%3Dshow /cmd reg-edit-reg /id 2 /del %2Ffaststart+%2Fh245-tunneling+%2Frtp-dtmf+%2Fsig-dtmf+%2Fdirect-sig+%2Fsip-hold-xfer /op OK /enable on /prot H323 /gk-addr primgk /alt-gk secgk /gk-id gkid /e164 number /h323 name /proxy /proxy2 /ep-addr epaddr /stun-srv /auth-name /gk-pwd ******** /gk-pwd* ******** /tones 0 /enblock /coder.model G711A /coder.frame 60 /lcoder.model G711A /lcoder.frame 30 /coder.srtp 0 /reg-ttl /userid admin

From this, you would remove the decoration as well as the /redirect option with parameter, which leaves

mod cmd PHONE/USER-UI reg-edit-reg /cmd reg-edit-reg /id 2 /del %2Ffaststart+%2Fh245-tunneling+%2Frtp-dtmf+%2Fsig-dtmf+%2Fdirect-sig+%2Fsip-hold-xfer /op OK /enable on /prot H323 /gk-addr primgk /alt-gk secgk /gk-id gkid /e164 number /h323 name /proxy /proxy2 /ep-addr epaddr /stun-srv /auth-name /gk-pwd ******** /gk-pwd* ******** /tones 0 /enblock /coder.model G711A /coder.frame 60 /lcoder.model G711A /lcoder.frame 30 /coder.srtp 0 /reg-ttl /userid admin

This command can either be sent - prefixed with an exclamation mark via HTTP GET - (such as http:/x.x.x.x/!mod cmd PHONE/USER-UI reg-edit-reg /cmd reg-edit-reg /id 2 ...) or used right away in an update script.

Known Problems

Unknown Module Name

Sometimes, the administration logging will not output the proper module name for the !mod cmd syntax.

For example, adding a wakeup call will show something like

PBX submit-wakeup /cmd submit-wakeup /xsl pbx_edit_wakeup.xsl /guid 13e3b070e909d311bb090090331e1486 /loc play /bool ckl-bool /h 1 /m 2 /s 3 /name sourcename /num 12345 /retry /wakeup /save OK /userid inno

When you try to use this as http://x.x.x.x/!mod cmd PBX submit-wakeup /cmd submit-wakeup ..., the device will not recognize the module and issue a simple ? as response. In this case, the correct module is PBX0/ADMIN instead of PBX.

If you try http://x.x.x.x/!mod cmd PBX0/ADMIN submit-wakeup /cmd submit-wakeup /guid 13e3b070e909d311bb090090331e1486 /loc play /bool ckl-bool /h 1 /m 2 /s 3 /name sourcename /num 12345 /retry /wakeup it will work just fine.

Unfortunately, you have to guess the correct module name. So if it does not work and you receive the ? response, you can have a look at the config file (with Maintenance/Diagnostics/Config-Show) and watch out for reasonable module names. In our case, you would find config change PBX0 ADMIN.

Unknown GUID

In some cases, the above method will not work. Consider for example editing the Groups list of an PBX object. The resulting log would be something like

20130312-144558 CMD inno@172.16.68.130 PBX submit-groups /cmd submit-groups /xsl pbx_edit_groups.xsl /guid 30523849e909d31193d400903300057f /loc home /grp-name Alle /grp-dyn /grp /grp-name Bine /grp-dyn /grp /grp-name Christoph /grp-dyn /grp /grp-name Durchsage /grp-dyn /grp /grp-name Info /grp-active on /grp-dyn /grp /grp-name /grp-name /grp-dyn /grp-add /save OK /userid inno

The problem here is, that the object that is to be changed is identified by its GUID and this certainly will vary so that your command would work only on this exact same system. The way to work around this is to replace the /guid 30523849e909d31193d400903300057f with /guid * /cn cn-of-object.

The method shown will set all parameters contained in a single configuration UI web page. Options which are not specified are set to a default value. As a result, you must specify all parameters of a page, otherwise you risk changing existing parameters. In most cases, this method is thus suitable for initial device configuration only. You may however query the current values before to implement a read-modify-write-cycle. The command to query the current settings can be determined the same way. It will look something like mod cmd PHONE/USER-UI reg-edit-reg /xsl reg_edit_reg.xsl /cmd reg-edit-reg /id 2 /op show /userid admin.

Proper Encoding

When sending the command via HTTP GET, you need to url-encode it properly.

Using the Mechanism for Device Status Queries

The mechanism can also be used for querying the device status. The approach is similar: you turn on administration logging as explained above and navigate to the part of the admin user interface which shows the data you are interested in. In the log, you will see the cmd to use.

For example: when you obtain the current PBX user list, you will find the log line

20180626-152726 CMD admin@x.x.x.x PBX show /cmd show /loc * /pseudo-type * /search /search-loc /search-grp /xsl pbx_objs_left.xsl /userid admin.

From this, you extract the URL

https://your-pbx-ip/!mod cmd PBX0/ADMIN show /cmd show /loc * /pseudo-type * /search /search-loc /search-grp

which will output the queried data in raw XML format.

The PHP Update Server

The PHP based Update Server V2 can use such commands to collect data from all the devices. See the queries tag. Using the above example, you could have a setting like <queries> 

<query id="users" title="PBX Users">
 <cmd>mod cmd PBX0/ADMIN show /cmd show /loc * /pseudo-type * /search /search-loc /search-grp</cmd>
 <applies>pbx</applies>
</query>

</queries>

Related Articles

Retrieved from "https://wiki.innovaphone.com/index.php?title=Howto:Effect_arbitrary_Configuration_Changes_using_a_HTTP_Command_Line_Client_or_from_an_Update&oldid=50530"