Howto:PHP based Update Server V2

From innovaphone wiki
Jump to navigation Jump to search
Tools clipart.png FIXME: "work in progress"

Applies To

This information applies to

  • all innovaphone devices
  • web server running PHP 5 (e.g. Linux Application Platform)

All Versions.

By default, the Update Manager mechanism reads a file that corresponds to the device type (e.g. update-ip222.htm). While this makes sense (update scripts may vary by device type), it is sometimes tedious, as you have to edit a huge amount of files which typically are (at least partly) identical.

Here is a PHP script that can be used as an Update Server that allows you to simplify the handling of update scripts. It also includes a mechanism that makes sure that all devices always have the same firmware installed as a given master device has. Finally, it implements a straight forward configuration backup scheme.

This article describes version 2 of this update server. The previous version is described in Howto:PHP_based_Update_Server. The enhancements are

  • Status user interface showing all known devices
  • Ability to roll out custom device certificates
  • Ability to provide configuration files to MTLS-authenticated devices only (e.g. in order to keep certain configuration settings secure)
  • Hide configuration files from public read access

More Information

Requirements

The update server script requires a web server with working PHP 5.3 or higher platform. It has been tested with Apache and ligHTTPD (on a Linux Application Platform). On IIS, neither the certificate roll-out nor the MTLS authentication or configuration backup works with IIS.

The platform running the PHP scripts must have a valid time setting!

Features

The update server can

  • update all your devices with boot code and firmware that corresponds to the versions running on a reference device of your choice
  • save backups of your devices configuration. Backups are saved only if the configuration changed since the last backup
  • invoke your own update scripts depending on
    • various phases (e.g. you can have staging scripts which are only executed once and normal scripts which are executed in normal operation later on)
    • devices classes (e.g. you can have different scripts for phones and gateways)
    • environments (e.g. you can have scripts for your internal devices and others for devices in home offices)
    • the device serial number
  • roll out customer specific device certificates
  • roll out update scripts to devices only that have identified themselves with a valid device certifictae (MTLS)

Installation

On the Linux Application Platform

Here is how you would install it on the LAP. Some of the steps may not be necessary if you don't want to use all features.

On the Linux Application Platform, you would

  • open the LAP's file system using a SFTP client such as e.g. WinSCP (if you have not yet changed it, the default credentials will be root/iplinux, see Concept Linux Application Platform). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
  • create a new root directory underneath /var/www/innovaphone/mtls, e.g. /var/www/innovaphone/mtls/update
  • copy the following files in to this directory
    • config.dtd
    • config.xml
    • update.php
    • user-config.xml
  • create a sub-directory called web underneath your root directory, copy the following files in to this directory
    • cer.png
    • hide.jpg
    • scripts.jpg
    • touch.gif
    • trash.gif
    • update.png
    • style.css
  • create a sub-directory called admin underneath your root directory, copy the following files in to this directory
    • admin.php
  • create a sub-directory called classes underneath your root directory, copy the following files in to this directory
    • updateserver.class.php
  • change owner and group of all files and directories to www-data, change mode to 0600 for all files and 0700 for all directories
  • log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be admin/linux, see Concept Linux Application Platform) and open the its Administration/Web Server/Change web server properties and public access to the web/webdav configuration UI. Add the following paths to Public Web Paths (assuming your base directory is called update):
    • /mtls/update
    • /mtls/update/web
    • /mtls/update/fw/ (note the trailing slash!)
make sure that no other sub-directories of update are listed
make sure you have no trailing '/' in any of these paths
this will make sure the update server's admin user interface is not accessible to the public

At this point, you should be able to access the update server's admin user interface, e.g. http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status. However, the only thing you see is an empty list of devices (that is, an empty page). Please note that your browser should ask you for a password for this page (unless you already entered it before).

If you want to setup MTLS-restricted Delivery of Update Scripts

If you think you have sensitive information in your update scripts, you should make sure to deliver such scripts to you own verified devices only. This can be done by authenticating calling devices with mutual TLS (MTLS). In this case, the calling device must use HTTPS to retrieve the update script and present a trusted client certificate that identifies itself as the calling device (that is, has the device serial as the certificate's common name (CN)).

For this feature, you need to Configure mutual TLS in the LAP's Administration/Web Server panel. Simply tick the Active check-mark and select an appropriate MTLS Port. The port must not conflict with any other TCP port used on the LAP, so neither 80 nor 443 is a good choice. 444 is a good choice. Although it is assigned to the snpp protocol by IANA, it is not used by the LAP (and probably rarely used anyway).

If MTLS is already activated on your LAP, simply take note of the currently configured MTLS Port.

On an Apache Server running on the Windows Operating System

Tools clipart.png FIXME: "to be done"

Configuration

If you intend to deliver your update scripts with MTLS (that is, with HTPS und mutual certificate check), you will need to have the full name of your certificate Authority (CA) as it is noted as Common Name (CN) in your CA's certificate. Also, you will need a PEM version of your CA's public key (a PEM version of a certificate is a text file that begins with a line like -----BEGIN CERTIFICATE-----).

Also, you need to know the MTLS Port configured in your LAP (see If you want to setup MTLS-restricted Delivery of Update Scripts above).

All tweakable parameters are set in user-config.xml. You may want to use an XML-capable editor such as notepad++, netbeans or Visual-Studio for editing. if your editor supports it, you benefit from the document type description (DTD) provided in config.dtd.

Delivering Firmware and Boot Code

At this point, you can simulate a device by requesting an update script using an URL like http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4 in your browser (please note that this URL should not ask you for a password). Most likely, your browser will wait a little while and then say something like: 

...
# failed to use cached data (cache not current), retrieving info online
# cannot get PBX info: cannot access http://yourmasterdevice.youdomain.tld/CMD0/box_info.xml, reading cache
# cannot get cached PBX info: cannot access cache/master-info.xml - exit

This is because you did not yet specify the master device which always runs the reference firmware.

The idea here is that you have one innovaphone device in your system where the firmware is always manually updated. All other devices shall follow this reference firmware. The update server will deliver the firmware that runs on the master device to calling devices. For this to work, you need to set the info attribute of the master tag and leave everything else as is.

Remember that you do all your local configuration changes in user-config.xml, which probably looks like this:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE config SYSTEM "config.dtd"> <config>

</config>

As master is a first level tag, you can add it directly underneath the opening <config> tag. The only thing we need to define right now is the path to read the firmware information from your master device. Let's say your reference device has the IP address 172.16.0.10, you end up with

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE config SYSTEM "config.dtd"> <config> <master info="http://172.16.0.10/CMD0/box_info.xml"/> </config> (you could use a DNS name instead of the IP address of course). The info URL is used by the update server itself only, it is never used by devices requesting an update script.

When you refresh the page that simulates a device requesting an update script, the output should now change to something like 

...
# failed to use cached data (cache not current), retrieving info online
# current firmware (unknown) does not match required firmware (130178)
...

This is to say that your master device runs firmware 130178 and the calling device does not (actually, as the calling client is simulated by your browser, it does not transmit its current firmware to the update server so it is (unknown)).

In order to actually update the clients with firmware and boot code, the files must be made available to the calling client somehow. This is done by specifying an URL in the prot and boot commands sent to the calling device: 

...
# current firmware (unknown) does not match required firmware (130178)
mod cmd UP0 prot http://update.yourcompany.com/mtls/update/fw/130178/ ser 130178
# current boot code (unknown) does not match required boot code (130112)
mod cmd UP0 boot http://update.yourcompany.com/mtls/update/fw/130112/ ser 130112
...

By default, the URL generated points to a sub-directory of your update server called fw: http://update.yourcompany.com/mtls/update/fw/130178/. Note that this default URL expects sub-directories underneath the fw directory which correspond to the firmware and boot code build number. The file structure thus would be like 

/var/www/innovaphone/mtls/update/fw
                                   /130178
                                          /ip232.bin
                                   /130112
                                          /boot232.bin

Note that the URL ends with a slash (/). This instructs the calling device to append the appropriate file name itself when retrieving the file (see the prot command for details).

However, you can also specify any other URL by setting the url attribute in the fwstorage tag of your user-config.xml. In this attribute, certain meta words will be replaced (see the fwstorage tag for details). The default setting for example is fw/{build}/.

You can disable firmware and boot code updates altogether by setting the info attribute in the master tag to en empty value.

Your own Update Script Files

The update server will deliver update scripts to calling devices which are synthesized from a number of update script snippets which you define yourself. The idea is that many devices share parts of their configuration while other parts are different. This depends on

  • the device class (e.g. a phone or a gateway)
the device class is automatically derived from its model. In fact, a single device may be in multiple classes. For example, an IP232 is in these classes: phone, pre_opus_phone, phone_newui which basically says that its a phone and has no OPUS codec yet but a "new" user interface (as opposed to the old one found e.g. on an IP110). A number of useful classes are pre-defined, but you can add your own in user-config.xml.
  • the device's environment (e.g. home-office, branch-office)
These reflect that fact that devices may need different configuration if they are in different locations (or environments). The update server does not know about a device's environment, which is why you need to configure it in to the devices update URL if you need this. By default, there is a single environment defined called default, but of course, you can add your own
  • phase
configuring devices may need multiple phases to go through. If more than one phase is defined, the device will go through all phases sequentially, which is why a phase has a numerical seq attribute. Phases are went through in order of this attribute. When the device has reached the last phase, it will stay there. By default, there is only one phase called update

You can define update script snippets for any combination of device, environment and phase. You do so simply by placing appropriate files in to the scripts directory on your update server.

Let's have a closer look at the web page we used to simulate a device calling for an update script before (http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4). It will show you all the possible files it would deliver to the device: 

# possible files (from scripts):
# scripts/update-all-00_90_33_00_00_00.txt does not exist
# scripts/update-all-default.txt does not exist
# scripts/update-phone-00_90_33_00_00_00.txt does not exist
# scripts/update-phone-default.txt does not exist
# scripts/update-pre_opus_phone-00_90_33_00_00_00.txt does not exist
# scripts/update-pre_opus_phone-default.txt does not exist
# scripts/update-phone_newui-00_90_33_00_00_00.txt does not exist
# scripts/update-phone_newui-default.txt does not exist

The update script snippet files need to have proper names to define when they should be delivered. As you can see, they all start with update- which means that they apply to devices which are in the update phase. As by default there is only a single phase defined, all possible file names start with update-.

The next part here is either phone-, pre_opus_phone-, phone_newui- or all-. This is because the calling IP232 is in three classes, so all respective snippets will be delivered to it. all however is a wild-card. That is, such files will be delivered to all devices, no matter what class they are in. You may wonder why there was no all for the phase. This is because there is only a single phase defined. If there would be more, the all-variation of the phase-part of the file name would be appear.

The third part finally is either default or 00_90_33_00_00_00 in our case. default is the name of the only environment that is defined by default. 00_90_33_00_00_00 is the device's serial number which is treated as an implicitly defined environment name. This allows you to deliver certain snippets to a single device only.

Now let's create an update script snippet that is delivered to all phones in the default environment when they are in the update phase. The file name (which looks like phase-class-environment.txt) has to be update-phone-default.txt therefore. Just for an exercise, let us set the device name (as shown in the browser's title bar) to This is a Phone!. The command to do so is config add CMD0 /name This+is+a+Phone%21, so your file may look like this 

# set the device name
config add CMD0 /name This+is+a+Phone%21

(btw: did you observe that config line arguments need to be url-encoded?). Now create the file and upload it in to the scripts directory of you update server. When you now refresh the page which simulates the device calling for an update script, you will see something like this: 

...
# newest script (scripts/update-phone-default.txt) 11s old
# files being updated (scripts/update-phone-default.txt 11s old, waiting for at least 90s to expire)

When you update multiple script snippets, it is often undesirable that a device retrieves an inconsistent state of the scripts you are working on (e.g. if you already have saved one but not yet the other). To avoid this, the update server will look at the files modification dates and if one of those that needs to be delivered to the device is younger than 90 seconds, it will not send any of them at all.

So when you wait for the 90 seconds to pass and refresh the page again, you will see something like this: 

# firmware build info cache is current
# phase: update, nextphase: , environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
...
# scripts/update-phone-default.txt 4.1 mins
...
#     scripts/update-phone-default.txt
# { begin script 'scripts/update-phone-default.txt' 
# set the device name
config add CMD0 /name This+is+a+Phone%21


# end script 'scripts/update-phone-default.txt' }

# trigger reset if required
config write
config activate
iresetn

As you can see, your snippet has been delivered by the update script. However, the update server has also added some trailing commands which write back the config to the devices flash memory (config write), activate it (config activate) and trigger a reset if needed (iresetn).

If there are multiple snippets available for a calling device, all of them are concatenated in the sequence shown in the header of the returned script (where the possible file names are listed)

Device Status

When you have a lot of devices which are served by the update server, you may want to have a list of these devices along with some useful information regarding each devices.

You can enable this by defining the status tag in your user-config.xml. So open the file and add the tag right next to the master tag you added before:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE config SYSTEM "config.dtd"> <config> 

   <master info="http://172.16.0.10/CMD0/box_info.xml"/>
   <status
       dir="status"
   />

</config>

When you have done so, please refresh the page that simulates your calling device and then open http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status. You will now see a device list (well, a list with a single device, the one you simulated using your browser). The list will show some information regarding the devices that requested an update script lately. For more options, see #status.

Device Backup

It is generally useful to have recent backups of all of your device configurations. The update server supports that if you enable it by defining the backup tag in your user-config.xml. Simply put it right next to the master or status tag you added before:

... 

   <backup
       dir="backup"
   />

If you have done so and then refresh the page that simulates your calling device, you will now see 

...
# scripts/update-phone_newui-default.txt does not exist

mod cmd UP0 scfg http://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m

instead of 

...
# scripts/update-phone_newui-default.txt does not exist

# Backups not enabled in config

When a client requests an update script the next time, this will initiate a configuration backup which is stored underneath the backup directory. For each device, a sub-directory is created and all backup files are stored therein. By default, the last 10 differing configuration backups are kept.

Controlling the Time-frames when Snippets are delivered

The update client built-in to innovaphone devices allows to restrict updates to certain time frames (e.g. only during the night). This can be controlled using the times command.

You can configure the update server to use the time commands by setting the allow and initial attributes in the times tag in your user-config.xml. 

   <times 
       allow="22,23,0,1,2,3,4" 
       initial="1"/>

If either the allow or initial attribute is present, the update script will contain a line like 

...
# Restricted times
mod cmd UP1 times  /allow 22,23,0,1,2,3,4 /initial 1

In the example above, all update script activity will occur only between 10pm and 5am (local device time). For more details, see Concept Update Server

Using and Enforcing HTTPS

Your devices can either use HTTP or HTTPS to access the update server. In normal operation, the update server will

Delivering Custom Certificates

Using multiple Phases

Migrating old PHP Update Server Installations

Update Script Query Arguments

Complete Parameter Reference

Note: attributes are marked with an at (@) prefix. So master/@info refers to the info attribute in the master tag.

The following tags and attributes are available in the user-config.xml file:

master

Defines the reference device where the firmware and boot code information is taken from.

/master/@info
the URL to the device info data. Set it to an URL like http://your-reference-device/CMD0/box_info.xml. Please note that this device must not have the Password protect all HTTP pages set in Services/HTTP/Server.
/master/@expire
the firmware info cache lifetime. The firmware information is cached in a file (to make sure this information is present even if the reference device is off-line). The cache will not be refreshed before the expire time (in seconds) is expired
/master/@cache
the cache file name. The web server must be able to write this file (see Installation above)

   <master 
       info="http://172.16.0.10/CMD0/box_info.xml"
       expire="3600"
       cache="cache/master-info.xml"/>

fwstorage

Defines from where the device will retrieve the firmware files for updates.

fwstorage/@url
defines the URL to retrieve the files from. In this URL, the following meta words will be replaced as follows:
  • {build} - the requested firmware or boot-code
  • {model} - the devices type (e.g. IP232). This is derived from the type query argument used in the update URL which is set to the value #t which in turn is expanded to the device type of the device requesting the update script
  • {filetype} - the type of the required file, either boot or prot

Note that if the url ends with a slash (/), the calling device will automatically append the name of the requested file. In this case, the file system the URL points to must therefore contain sub-directories for each firmware build which contain the corresponding firmware builds (e.g, fw/12345/ip232.bin). If url is not an URL (as is the case for the default value fw/{build}/), it is treated as a sub-directory underneath the script directory 

   <fwstorage url="fw/{build}/"/>

backup

Defines where backup files are kept.

backup/@dir
the directory underneath the script directory where backups are stored
backup/@nbackups
the number of different backup files kept
backup/@scfg
the target URL for the scfg command. If this is not an url, it is interpreted relative to the script directory URL. You can add more options for the scfg command, like in scfg="update.php?mode=backup&hwid=#h&sn=#m ser hourly /force 1" (this example will make sure backups are attempted only once per hour, so as to reduce load on the server).

   <backup 
       dir="backup"
       nbackups="10"
       scfg="update.php?mode=backup&hwid=#h&sn=#m"
   />

status

Defines details regarding the state kept for device requesting an update script.

status/@dir
the directory the status files are kept in (e.g. status). Used as the name for a sub-directory underneath your install directory on your web server. You must make sure that files in this directory cannot be read by anyone without proper authentication, as such files may contain sensitive information.
status/@expire
if set and not empty, devices which have not requested an update script will be removed from the inventory after n seconds. For example, expire="7776000" will forget about devices after 90 days with no contact
status/@missing
devices are shown in a different colour (indicating that they are missing) after n seconds. For example, missing="604800" will flag devices as missing after 7 days with no contact
status/@refresh
if set and not empty, the admin user interface showing the known devices will refresh the status of all shown devices each n seconds

   <status 
       dir="status" 
       expire="7776000" 
       missing="200" 
       refresh="10"/>

times

Defines details regarding the delivery of update scripts to requesting devices.

times/@dir
the directory the update scripts are stored in. For security reasons, you may want to make sure that files in this directory cannot be read without proper authentication.

These attributes define the arguments of the times command. If neither allow nor initial is set, no times command is used (that is, the update scripts will be processed at all times).

times/@allow
the hours to be used in the times command
times/@initial
the minutes to be used in the times command

Delivered update scripts can include a check command if the check attribute is set to true. . In this case, the devices will executed the scripts again only when you have edited/changed them.

times/@check
if set to true, update scripts will be executed once only (unless their contents change)

When editing a number of update scripts, it is often not desirable if one changed script is already executed before another is changed too. When the grace attribute is set to a positive value, no script at all is delivered to requesting devices unless n seconds have expired since the last edit. For example, setting grace to 90 gives you one and a half minute to finish all your edits.

times/@grace
defines the number of seconds that must expire before update script changes take effect

The update server works in either fast or normal mode. In fast mode, update scripts have to be requested more frequently, for example to step through multiple staging phases faster. This is enforced by modifying the calling device's Interval setting in [Reference11r1:Services/Update | Services/Update ]] and setting it to 1 in fast mode.

times/@interval
polling interval in minutes for normal operation (that is, when all staging s done)
times/@polling
when you are using multiple phases (e.g. staging and update), this defines the number of seconds to wait before the device reads the scripts for the next phase (see provision command) (please do not modify the default value)

In some installations it may be desired to deliver update scripts with HTTPS only or even only to calling devices which have identified themselves with a proper TLS certificate.

times/@forcehttps
if set to true, update scripts will only be delivered if the device call in with HTTPS. If the device is ready to receive an update script and still calls in with HTTP only, its Command File URL will be re-configured to use HTTPS automatically.
times/@httpsport
if you use a non-standard port for HTTPS access to update scripts, it can be defined here
times/@httpsurlmod
if your HTTPS URL differs from the HTTP URL, you can specifiy a modifier. It has the form /pattern/replacement where pattern is a PHP PCRE pattern. For example, /mtls// will remove the string mtls from the URL used by the device to create the HTTPS URL to use
times/@forcetrust
if set to true, update scripts will only be delivered if the device call in with HTTPS and a valid and trusted client certificate that identifies itself as the devices it claims to be

   <times 
       dir="scripts" 
       allow="" 
       initial="" 
       check="true" 
       polling="5" 
       interval="15" 
       grace="90" 
       forcehttps="true" 
       httpsport="444" 
       forcetrust="false" 
       httpsurlmod="/mtls//"/>

phases

Defines the scripting phases. In many installations, there are initializations which should be performed once only. This is known as the staging phase. Once this is done, the devices continue with the execution of the normal update scripts (this phase is known as update by default). In the (unlikely) event that you want more or less phases, you can add/remove phase tags.

phases/phase

phases/phase/@id
the name for the phase
phases/phase/@seq
the sequential number for the phase. Phases are stepped-through in the numeric order defined by their seq atribute.

By virtue if the seq attribute, you can insert phases in to the set of phases defined by default, which is 

   <phases>
       <phase id="staging" seq="100"/>
       <phase id="update" seq="200"/>
   </phases>

For example, 

   <phases>
       <phase id="phase" seq="150"></phase>
   </phases>

will insert a custom phase myphase as second phase.

environments

Defines the distinguished environments. Devices can have zero or more environments associated. The environments a device is considered to be in must be passed as ?env=name1,name2,.. URL query arg in the update url. Update scripts for all environments listed will be applied. The default config file defines the environments intern and homeoffice but you can define your own if you like.

environments/environment

Each environment may have a number of sub-tags of type implies. It contains the id of another environment. If a device is in an environment with an implies sub-tag, it is assumed that it is in the implied environment also.

environments/environment/@id
the name for the environment

   <environments>
       <environment id='hq'>
           <implies>intranet</implies>
       </environment>
       <environment id='intranet'/>
       <environment id='homeoffice'/>
   </environments>

classes

Defines the available device classes. Devices of different classes (e.g. phones and gateways) can have different update scripts. The device class is derived from the #t (device type) query arg of the update script URL (which is why you must configure it in the update URL). By default, the classes phone, opus_phone, pre_opus_phone, phone_oldui, phone_newui, mobile and gw are recognized. A given device can be in multiple classes and will execute all update scripts available for these classes.

classes/class

Each class has a number of sub-tags of type model. It contains the value replaced for the #t query arg. The models listed belong to the class.

classes/class/@id
the name of the class

   <classes>
       <class id="gw">
           <model>ip0010</model>
           ...
       </class>
       <class id="phone">
           <model>ip110</model>
           <model>ip232</model>
           ...
       </class>
       <class id="phone_oldui">
           <model>ip110</model>
           ...
       </class>
       <class id="phone_newui">
           <model>ip232</model>
           ...
       </class>
   </classes>

stdargs

Better don't touch :-)

customcerts

innovaphone hardware devices come with a device specific, trust-able device certificate. However, in many situations it is desirable to roll-out customer-created custom certificates to all devices. The update server can do this. This will replace the shipped devices certificates both on hardware devices (where all such certificates are derived from innovaphone's certificate authority) as well as on soft devices which run with a self.-signed certificate by default (such as the software-phone or myPBX for Android/iOS).

customcerts/@dir
the name of the directory underneath your installation directory which stores device certificates. you should make sure that this directory cannot be accessed without proper authentication
customcerts/@CAkeys
a file name pattern (e.g. CAkey*). All files in customcerts/@dir which match the pattern mut contain PEM encoded public keys of all the CAs you trust for device uthentication (usually it is only one and the public key of your CA)
customcerts/@CAtype
must be manual currently
customcerts/@CAname
a comma-separated list of CA names. Devices presenting a certificate signed by one of these CAs will be considered as having a valid certificate. Otherwise, they wil be instructed to create a certificate signing request (CSR) for subsequent submission to your CA
customcerts/@CAnamesep
defines the name separator for customcerts/@CAname. Teh default is , and you must chaneg it to a different value if one of your CAs includes a comma in its name
customcerts/@renew
if set and not 0, certificates are replaced by new ones n days before they expire
customcerts/@storeky
must be set to true if the update server shall roll-out custom certificates to devices with pre-v12r2 firmware

When the update server determines that a device calls in with an un-trusted or expired certificate, it will have it create a signing-request for a new certificate. The requested certificate properties can be defined:

customcerts/@CSRkey
the key size, e.g. 2048-bi
customcerts/@CSRsignature
the signature algorithm, e.g. SH256
customcerts/@CSRdn-cn
the CN (common name) part used for the DN
customcerts/@CSRdn-ou
the OU (organizational unit) part used for the DN
customcerts/@CSRdn-o
the O (organization) part used for the DN
customcerts/@CSRdn-l
the L (locality) part used for the DN
customcerts/@CSRdn-st
the ST (state or province) part used for the DN
customcerts/@CSRdn-st
the C (country) part used for the DN (note: CSRdn for many CAs, must be a 2-letter ISO country code
customcerts/@CSRsan-dns-1
the first of up to three DNS names
customcerts/@CSRsan-ip-1
the first of up to two IP addresses

Within the set of CSR attributes, the following meta-words will be replaced:

  • {realip} : the real IP address of the device as reported in the ip=#i query argument
  • {ip} : the IP address of the device as seen by the update server
  • {proxy} : the IP address of the reverse proxy the device used to reach the update server
  • {sn} : the serial number of the device as reported in the sn=#m query argument (e.g. 00-90-33-03-0d-f0)
  • {hwid} : the hardware-id of the device as reported in the sn=#m query argument (e.g. IP1200-03-0d-f0)
  • {name} : the Device Name (set in General/Admin) of the device
  • {rdns} : the DNS name found in a reverse DNS lookup for the real-ip address reported by the device (see {realip}) above

   <customcerts 
       dir="certs" 
       CAkeys="CAkey*" 
       CAtype="manual" 
       CAname="innovaphone-INNO-DC-W2K8-Zertifizierungsserver" 
       CAnamesep="," 
       CSRkey="2048-bit" 
       CSRsignature="SH256" 
       CSRdn-cn="{hwid}" 
       CSRdn-ou="" 
       CSRdn-o="" 
       CSRdn-l="" 
       CSRdn-st="" 
       CSRdn-c="" 
       CSRsan-dns-1="{name}.company.com" 
       CSRsan-dns-2="{hwid}.company.com" 
       CSRsan-dns-3="{rdns}" 
       CSRsan-ip-1="{realip}" 
       CSRsan-ip-2="" 
       renew="90" 
       storekey="true"/>

Download

  • not yet available to the public

Related Articles

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