Phone background pusher
Use this tool to push IP Phone backgrounds automatically to your Cisco IP Phones.
- 1 Requirements
- 2 Supported models
- 3 Configuration
- 4 Execution
- 5 Debugging
- 6 Development
- 7 Notes
- 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:
- 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...
- The following modules need to be installed:
- 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.
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:
- Only supported on firmware version 9.4(2) and newer
- Only supported on firmware version 9.4(2) and newer
The Enterprise Parameter "Phone Personalization" needs to be set to Enable in order for the phones to accept the backgrounds to be pushed.
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.
This is a normal End User, with a configured password.
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.
This user must belong to the "Standard CCM End Users" group or equivalent, containing the roles "Standard CCM End User" and "Standard CCMUser Administration".
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
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.
- 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):
The List.xml files are not used by pbp. The supplied background files are valid for the following phones:
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.
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.
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$
"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.
The current development can be followed on Github at https://github.com/azevedo-manuel/pbp You can use GitHub to submit bugs.