Phone background pusher

From ip tuning
Jump to: navigation, search
Remember this is a command line tool! If you're using Windows, clicking on the icon will not show anything! Use the command line!
IP Phones have flash memory! Re-writing flash decreases performance and flash reliability with time and may break your phone. Don't push backgrounds to the phones so often!

Use this tool to push IP Phone backgrounds automatically to your Cisco IP Phones.

Requirements

  • Pre-compiled binaries exist for Windows.
  • If your want to run directly in Perl (Linux, MacOS X, Windows with Perl, etc...):
    • The following modules need to be installed:
      • Config::Std
      • LWP::UserAgent
      • XML::Bare
      • Getopt::Long
      • SOAP::Lite
    • Tested in Windows using http://www.activestate.com/activeperl, MacOS X and Debian Linux
      • The Windows version breaks if more than 6 phones are associated to the user. This seems some buffer issue that does not exist on the MacOS and Linux versions of Perl. Maybe if someone has a way to fix this...
  • Enterprise parameter "Phone Personalization" must be set to Enabled.
  • Background images for your phones
    • If you want multiple phone support, you need to create directories for each phone model (see bellow) and the images must have the same name across models (even though they have different resolutions and depths).
    • Each image must follow Cisco's guidelines for the phone model (resolution and depth)
  • A web server to store the images. This web server must be accessible by the phones, as the phones themselves will download the background images from this server
    • You can use CUCM TFTP's HTTP access (port 6970) to get the images. This way you can also create the correct directories in CUCM for standard phone backgrounds.

Supported models

This list is neither extensive of all supported models nor it was tested in all models. Use as a reference. Edit the source-code if it needs correction:

Model RISDB ID Resolution
7906 369 95x34x1
7911 307 95x34x1
7942 434 320x196x4
7962 404 320x196x4
7945 435 320x212x16
7965 436 320x212x16
7970 30006 320x212x12
7971 119 320x212x12
7975 437 320x216x16
7985 302 800x600x16
8811 36217 800x480x24
8841 683 800x480x24
8851 684 800x480x24
8861 685 800x480x24
8941[note 1] 586 640x480x24
8945[note 2] 585 640x480x24
8961 540 640x480x24
9951 537 640x480x24
9971 493 640x480x24
  1. Only supported on firmware version 9.4(2) and newer
  2. Only supported on firmware version 9.4(2) and newer
This IDs were obtained from CUCM 10.5. I have no reason to believe Cisco will change them in other versions, but this is not assured

Configuration

Enterprise service

The Enterprise Parameter "Phone Personalization" needs to be set to Enable in order for the phones to accept the backgrounds to be pushed.

"Phone Personalization Enabled" enterprise parameter

AXL user

pbp needs a user with AXL access in order to read phones and RISDB status. Best practices dictate you create an Application User just for this application. AXL calls are made in HTTPS, so credentials don't go in open text between your pbp application and CUCM.

This user must belong to a group with these two roles:

  • Standard AXL API Access
  • Standard CCM Admin Users

You can configure this user using the "axlusername/axlpassword" parameter pair, either as CLI arguments or on the pbp.conf configuration file. If unconfigured, pbp will try the end user username and password to reach CUCM's AXL interface.

"Application User" example


End User

This is a normal End User, with a configured password.

"End User" username configuration

This is the user were the phones are associated to. The user must own all the phones you want to update. pbp will only check for the phones associated to this user. All other phones will not be checked. The application will check each phone to see if it is supported to push background images.

"End User" associated devices

This user must belong to the "Standard CCM End Users" group or equivalent, containing the roles "Standard CCM End User" and "Standard CCMUser Administration".

"End User" group membership


If you do not configure an AXL username pbp will try to get AXL access using this username. In order for this to work this way, this user must then also have these roles:

  • Standard AXL API Access
  • Standard CCM Admin Users
This last paragraph is not recommend. Phones check for user authorization in unencrypted HTTP with Basic Authentication. Any traffic sniffer could reveal the AXL username and password! Use the "AXL Application User" for AXL connection and use the End User phone phone association instead

You can configure this user using the "bkgusername/bkgpassword" parameter pair, either as command line arguments or on the pbp.conf configuration file.

Background and background URLs

All backgrounds are composed of a background image and a thumbnail image. The thumbnail is 25% of resolution of the background image's resolution. This thumbnail is used on the phone's background selection menu.

pbp will push instructions to the phone, directing it to download the images from the given URL. This is done by pushing an URL to the phone.

These URLs support a substitution wildcard, the '*'. If present, for each valid phone model, pbp will replace the wildcard with the correct resolution for the phone model.


Example:

The resolution for the 7965 phone is 320x212x16, so pbp will replace the '*' for this resolution value.
If the thumbnailURL option is http://10.1.1.1/*/background.png, then pbp will instruct the phone to download the background from http://10.1.1.1/320x212x16/background.png

If you omit the wildcard, pbp will not replace anything and deliver the URL without modification.

A sample directory organization can be as follows (using the supplied samples at GitHub pbp repository):

Background-samples.png

The List.xml files are not used by pbp. The supplied background files are valid for the following phones:

  • 320x212x16
    • 7945
    • 7965
  • 640x480x24
    • 8941
    • 8945
    • 8961
    • 9951
    • 9971


pbp.conf configuration file

This file needs to be in the directory as the pbp script. If the file is not present, all mandatory parameters need to be defined in the command line arguments. Alternatively, you can define an different configuration file using the --conf or -c options. If undefined, the app will search for the pbp.conf in the same directory the app is running.

The file format is:

  • '#' represents a comment. It must always start at the beginning of the line. Anything you enter after it will be ignored.
  • A parameter starts the beginning of the line and it's on the left of either ':' or '=' signs
  • The parameter value is on the left of the ':' or '=' signs
  • A boolean parameter is either 0 (false) or 1 (true)

The shipped pbp.conf file is the following. Please note some options are not yet implemented, as marked.

# This is a comment
# All options defined here can be overwritten by command line switches, which 
# take higher priority.
# If the command line switch is not defined, then this configuration will take it's value
# If the switch is also not defined, the default value will be used. In case there is no 
# default value the app will not execute.


# Quiet operation
# If 0 then print progress messages. 1 the app returns no output to stdin
# DEFAULT: 0
#quiet: 1

# Devices per RISdb request
# Up to CUCM 9, RISdb limited the total number of devices per request to 200.
# From 9 onwards, the total limit is now 1000
# There's no validation of the total number of devices, so be careful!
#rischunksize: 200

# This section contains CUCM configuration
# This is the End User name that the phones are associated to
bkgusername: imguser
bkgpassword: imgpassword

# This defines the AXL user
# Usually this is an application user.
# If not defined, the app will try to use the bkgusername/bkgpassword pair
axlusername: axluser
axlpassword: axlpassword

# CUCM host address
# Here define either the host or IP address of the AXL server to connect to
cucm: 10.1.1.70

# This section contains the background image base URLs
# Because each phone model have different resolutions, the images must be
# prepared according to the documentation. Place the * wildcard for the
# script to replace it with the correct resolution path, example:
# Model 7965:
# thumbnailURL: http://10.1.1.1/*/background.png
# Will be expanded to:
# http://10.1.1.1/320x212x16/background.png
# If you omit the *, the same image will be pushed to the phone, regardless of the model
# Thumbnail URL
thumbnailURL:  http://10.1.1.70:6970/Desktops/*/carnations-tn.png
# Background URL
backgroundURL: http://10.1.1.70:6970/Desktops/*/carnations.png

# *** UNIMPLEMENTED ***
# This section contains the logging options 
# Logging enabled: 1. Logging disabled: 0
# DEFAULT: 1
logging: 1

# *** UNIMPLEMENTED ***
# Logging to a file. If no file given, logs to console
# Default: STDIN
logfile: output.log

Command line arguments

Manuels-iMac:pbp mazevedo$ ./pbp.pl --help

Usage: ./pbp.pl -options

where options are:
 --conf  or -c          Define an alternate configuration file. Parameters will still
                        overide configuration file values though
 --quiet or -q          Don't show any output. DEFAULT is '0'
 --bkgusername value    End user's username that has the phones associated with
 --bkgpassword value    End user's password
 --axlusername value    Application/End user username for CUCM AXL access.
                        If not present, assume same as 'bkgusername'
 --axlpassword value    Application/End user password for CUCM AXL access.
                        If 'axlusername' is not defined, assume same as 'bkgpassword'
 --cucm value           CUCM AXL server's address
 --thumbnailURL value   The URL where the thumbnail image is.
                        Use * to replace with phone model resolution directory
 --backgroundURL value  The URL where the background image is.
                        Use * to replace with phone model resolution directory
 --logging or -l        List phones that are being used and push status     ** NOT IMPLEMENTED **
 --logfile              Export to loggin to a file. DEFAULT: log into STDIN ** NOT IMPLEMENTED
 --version or -V        This program's version. When refering to bugs, get the version here
 --rischunksize         The number of devices per RIS request. DEFAULT is '200'
 --help or -h           This menu
 --debug or -d          Enable diagnostics debug messages

Only options with DEFAULT values are optional. All the remaining
need to be configured either in the pbp.conf or as an command line argument

All options are case sensitive!

Command line arguments will overwrite set parameters in the pbp.conf file (or alternate configuration file defined using --conf) during the script execution.

If a parameter is defined in the configuration file and is again defined in the command line argument, the command line argument takes precedence. This is useful when using with automated tasks, keeping the common parameters in the configuration file and the parameters that change as an argument.

If a parameter is undefined in the configuration file and is not supplied in the command line argument and if said parameter is mandatory, the application does not run.

Execution

With a properly configured parameters, a typical output should look like:

Manuels-iMac:pbp mazevedo$ ./pbp.pl
Found 8 device(s) associated to user 'imguser'
Found 3 device(s) registered
1/3 - Device 'SEP9CAFCA84C169' update status: Success
2/3 - Device 'CSFmazevedo' is not a supported model
3/3 - Device 'SEP9CAFCA84D025' update status: Success
Finished in 9 seconds!
Manuels-iMac:pbp mazevedo$

If using the -q or --quiet parameters, this output is suppressed.

Debugging

Before opening a ticket in GitHub, try to find out why the script is not working.

There are two ways to enable debug:

  • Command line (recommended)
    • This shows all debug messages after parameter collection
  • Setting the $debug variable to 1
    • This shows all debug messages, including parameter collection

The second method is not necessary, unless you need to troubleshoot how parameters are processed by the application.

Enabling debug shows pbp steps:

Manuels-iMac:pbp mazevedo$ ./pbp.pl -d
DEBUG > Using config file 'pbp.conf'
DEBUG > Main: Getting configuration file
DEBUG > Config file: File 'pbp.conf' found
DEBUG > Config file: axlpassword     = axlpassword
DEBUG > Config file: axlusername     = axluser
DEBUG > Config file: backgroundURL   = http://10.1.1.70:6970/Desktops/*/carnations.png
DEBUG > Config file: bkgpassword     = imgpassword
DEBUG > Config file: bkgusername     = imguser
DEBUG > Config file: cucm            = 10.1.1.70
DEBUG > Config file: dummy           = ** Undefined in config file **
DEBUG > Config file: logfile         = output.log
DEBUG > Config file: logging         = 1
DEBUG > Config file: quiet           = ** Undefined in config file **
DEBUG > Config file: rischunksize    = ** Undefined in config file **
DEBUG > Config file: thumbnailURL    = http://10.1.1.70:6970/Desktops/*/carnations-tn.png
DEBUG > Main: Getting configuration from command line
DEBUG > Final config: axlpassword     = axlpassword
DEBUG > Final config: axlusername     = axluser
DEBUG > Final config: backgroundURL   = http://10.1.1.70:6970/Desktops/*/carnations.png
DEBUG > Final config: bkgpassword     = imgpassword
DEBUG > Final config: bkgusername     = imguser
DEBUG > Final config: cucm            = 10.1.1.70
DEBUG > Final config: dummy           = 1
DEBUG > Final config: logfile         = output.log
DEBUG > Final config: logging         = 1
DEBUG > Final config: quiet           = ** Undefined **
DEBUG > Final config: rischunksize    = 200
DEBUG > Final config: thumbnailURL    = http://10.1.1.70:6970/Desktops/*/carnations-tn.png
DEBUG > Main: Validating if there are undefined options
DEBUG > Main: Querying the AXL database for phones associated with imguser
DEBUG > Get phone list: Found device 'SEP9CAFCA84C169'
DEBUG > Get phone list: Found device 'SEP9CAFCA84D025'
DEBUG > Get phone list: Found device 'CSFgina'
DEBUG > Get phone list: Found device 'CSFmazevedo'
DEBUG > Get phone list: Found device 'SEP123456789013'
DEBUG > Get phone list: Found device 'SEP123456789012'
DEBUG > Get phone list: Found device 'SEP123456789014'
DEBUG > Get phone list: Found device 'SEP123456789015'
Found 8 device(s) associated to user 'imguser'
DEBUG > Get phone status: Created 1 chunk(s), each with a maximum of 200 phones
DEBUG > Get phone status: Getting chunk 1
DEBUG > Get phone status: 2 phone(s) are registered in chunk 1
Found 2 device(s) registered
DEBUG > Main: Checking all devices. If registered, push background
DEBUG > Main: SEP9CAFCA84C169 : 10.1.1.101 is registered
DEBUG > PhoneInfo: Found model for ID '435'
DEBUG > Main: SEP9CAFCA84C169 model is '7945' and resolution is '320x212x16'
DEBUG > Main: Background URL to push to device SEP9CAFCA84C169 is 'http://10.1.1.70:6970/Desktops/320x212x16/carnations.png'
DEBUG > Main: Thumbnail URL to push to device SEP9CAFCA84C169 is 'http://10.1.1.70:6970/Desktops/320x212x16/carnations-tn.png'
1/2 - Device 'SEP9CAFCA84C169' update status: Success
DEBUG > Main: SEP9CAFCA84D025 : 10.1.1.102 is registered
DEBUG > PhoneInfo: Found model for ID '435'
DEBUG > Main: SEP9CAFCA84D025 model is '7945' and resolution is '320x212x16'
DEBUG > Main: Background URL to push to device SEP9CAFCA84D025 is 'http://10.1.1.70:6970/Desktops/320x212x16/carnations.png'
DEBUG > Main: Thumbnail URL to push to device SEP9CAFCA84D025 is 'http://10.1.1.70:6970/Desktops/320x212x16/carnations-tn.png'
2/2 - Device 'SEP9CAFCA84D025' update status: Success
Finished in 9 seconds!
Manuels-iMac:pbp mazevedo$

Troubleshooting

"No configured devices found"

If you get a message like this:

Manuels-iMac:pbp mazevedo$ ./pbp.pl
No configured devices found. You need to associated devices to user 'imguser'
or configure another user
Manuels-iMac:pbp mazevedo$

Chances are you have one of these three situations:

  • The AXL user is not correct
    • Check the password
    • Try accessing AXL's page using the axlusername/password:http://<cucmip>:8443/axl
      • If credentials is correct, you should get a message like this: "Cisco CallManager: AXL Web Service. The AXL Web Service is working and accepting requests. Use HTTP POST to send a request."
    • In newer CUCMs if you try too many times to login with a wrong password, CUCM considers it a hacking attempt and blocks the user. You need to unblock it on the user page to reset the hack count value.
  • Your End User has no phones associated
  • pbp cannot reach CUCM

x/x - Device 'SEP000000000000' update failed: 400 Bad Request

If you get something like this:

Manuels-iMac:pbp mazevedo$ ./pbp.pl
Found 8 device(s) associated to user 'imguser'
Found 3 device(s) registered
1/3 - Device 'SEP9CAFCA84C169' update failed: 400 Bad Request
2/3 - Device 'CSFmazevedo' is not a supported model
3/3 - Device 'SEP9CAFCA84D025' update failed: 400 Bad Request
Finished in 4 seconds!
Manuels-iMac:pbp mazevedo$

There are usually three causes for this:

  • Wrong image or thumbnail URL.
    • Use the debug parameter to get the URL that is pushed to the phone. Try it in a browser.
    • Note that both the background image and the thumbnail need to be correct for the phone to accept them
  • The size of the file is too big. Varies from phone to phone. For example, on the 7945, background images bigger than 320Kb generate this error. Having files in TFTP that work is not an indication that they will work using HTTP push!
    • You can check the size error with the debug parameter.
  • The "Phone Personalization" Enterprise Parameter is disabled

x/x - Device 'SEP000000000000' update failed: 500 read timeout

If you get this message it means the phone took more than 5 seconds to answer your request, download the image and report back to pbp:

Manuels-iMac:pbp mazevedo$ ./pbp.pl
Found 8 device(s) associated to user 'imguser'
Found 3 device(s) registered
1/3 - Device 'SEP9CAFCA84C169' update failed: 500 read timeout
2/3 - Device 'CSFmazevedo' is not a supported model
3/3 - Device 'SEP9CAFCA84D025' update failed: 500 read timeout
Finished in 11 seconds!
Manuels-iMac:pbp mazevedo$ ./pbp.pl
</pbp>

This does not mean the background image was not uploaded, only that the answer timed-out. The timeout value can be changed in the code. In the future this time-out can be defined in the configuration file.

== Submitting bugs ==

You can submit bugs in the projects GitHub repository.

Please execute this before submitting the bug:

<pre>
Manuels-iMac:pbp mazevedo$ ./pbp.pl -V

Application : phone background push - pbp
Version     : 0.4 - 09.Jun.2015
Copyright   : Manuel Azevedo
Platform    : darwin

Manuels-iMac:pbp mazevedo$

Include this data in your ticket request.

You can download the latest version here: https://github.com/azevedo-manuel/pbp/releases.

For Microsoft windows there is a pre-compiled binary in each release.

These binaries use Perl Package (PP). They contain a small run-time version of Activestate Perl that unzips into your %userprofile\temp% directory. These temporary files will not be deleted after being run for the first time for subsequent faster loading times. The folder that is created starts with par-.
The pre-compiled binaries are supplied as courtesy. I do not support them. I just compile them.

Development

The current development can be followed on Github at https://github.com/azevedo-manuel/pbp You can use GitHub to submit bugs.

Notes