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

==Applies To==
This information applies to

* all innovaphone Devices Version 7 and up

<!-- Keywords: enter keywords, foreign translations and/or synoyms not appearing in the article here for better search results -->

==More Information==

===Problem Details===
When the configuration of an innovaphone device shall be changed programmatically, there are generally two options
* apply changes using the <code>config change/add/rem</code> 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 <code>mod cmd</code> 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 

<code>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</code>

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

<code>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</code>

This command can either be sent - prefixed with an exclamation mark via HTTP GET - (such as <code>http:/x.x.x.x/!mod cmd PHONE/USER-UI reg-edit-reg /cmd reg-edit-reg /id 2 ...</code>) 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

<code>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</code>

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

If you try <code>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</code> 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 <code>config change PBX0 ADMIN</code>. 

==== 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

<code>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</code>

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 <code>/guid 30523849e909d31193d400903300057f</code> with <code>/guid * /cn cn-of-object</code>.

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 <code>mod cmd PHONE/USER-UI reg-edit-reg /xsl reg_edit_reg.xsl /cmd reg-edit-reg /id 2 /op show /userid admin</code>.

==== 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 

<code>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</code>.

From this, you extract the URL

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

which will output the queried data in raw XML format. 

==== The PHP Update Server ====
The [[Howto:PHP_based_Update_Server_V2 | PHP based Update Server V2 ]] can use such commands to collect data from all the devices.  See the [[Howto:PHP_based_Update_Server_V2#queries | queries ]] tag.  Using the above example, you could have a setting like
<syntaxhighlight lang="html5">
<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>
</syntaxhighlight>

== Related Articles ==
* [[Howto:PHP based Update Server V2]]

[[Category:Howto|{{PAGENAME}}]]