Duinsoft - Linux
Sunday 25 June 2017      | home | tools | contact

The 'pf-wrapper' script

Contents

Introduction

The pf-wrapper script can be used to install and update Adobe's Pepper Flash plugin on a Debian (or derivative) system. On Ubuntu and derivatives, using this script is not recommended, because Ubuntu has an Adobe maintained package called adobe-flashplugin which provides the plugin.
The plugin should work with Chrome, Chromium, Opera, Vivaldi or - with the help of Rinat Ibragimov's freshplayer plugin - Mozilla based browsers, like Firefox, Pale Moon, Iceweasel, IceCat and the SeaMonkey browser.

Earlier versions of this script were aimed specifically at updating the freshplayer plugin. This has been dropped, mainly because of the Debian package browser-plugin-freshplayer-pepperflash, which provides that plugin and appears to be keeping up with upstream development (although, at the moment of writing this, I am starting to wonder...). This package is also available for Ubuntu, by the way.
Versions before 2.1.0 used Google's Chrome package to retrieve the Pepper Flash plugin, but Google stopped supplying the plugin with the Chrome package.

This script is not distributed in a Debian package but in a tarball. It can be 'installed' in /usr/local/sbin, with some supporting files in the directory /usr/local/lib/pf-wrapper. Do not place the files there manually, but use the script's own functionality (see below).

If the script is installed, it can keep track of updates of Pepper Flash using a daily cron job. If it is not installed, you can still use it to install or update the plugin manually.

Link

Version 2.2.0 of the script is available in a tarball (SHA256 hash is 2e21610bffff000f05f3f0b059e12389db1fbf3f130fecc40bd3744b93e21575 - gpg signature is here). Just download and unpack it somewhere suitable.

Pepper Flash sources

There are other ways to get the Pepper Flash plugin, like installing:

The first two are well maintained and have no problem keeping the plugin up to date, but the last one's update mechanism is a joke. Actually, it has stopped working altogether, because it still tries to extract the plugin from Chrome.

If the script detects any of the first two on your system, it will not try to install or update the plugin unless you use the special option --force (you better have a very good reason to do that and you will have to fix any problems it may cause yourself...).
If pepperflashplugin-nonfree is installed, it will be ignored and you will be asked if you want to remove it. Unless you use the 'quick install' (see below) or the special option --remove-pfnf, in which case it will be removed automatically. Keeping it installed is not recommended. Applications that use the plugin search for it in various locations and even if the search order does not cause problems now, it may do so in future.

Even if the script is set not to handle the plugin, you can still use it to notify you of updates.

Overview of commands and options

The --help option of the script currently provides this list of functions and options:

	Usage: pf-wrapper [OPTION]... [get|plugin|remove|status]
	       pf-wrapper install|purge

	Main commands:
	  get        download the most recent version of the script
	  install    install the script and the plugin with sensible default options
	  plugin     install or update the plugin
	  purge      remove everything - CAUTION: includes deleting the script itself!
	  remove     remove the plugin
	  status     show some state information about the script and the plugin

	Options:
	  -a         allow the cron job to update the plugin
	  -c         install a cron job to run daily update checks
	  -i         install this script in /usr/local/sbin
	  -n         use notifications to report the cron job's findings and actions
	  -p         purge related files and directories when uninstalling the script
	  -q         produce no apt-get/wget output (-q) or no output at all (-qq)
	  -r         remove the script's cron job
	  -s         allow the cron job to update the script
	  -t SECONDS number of seconds to keep notifications on screen
	  -u         uninstall the script if -i was used earlier
	  -w OPT,... wipe stored options (comma separated list, no leading dashes)

For convenience, -c includes -i and -u includes -r. However, -a, -n, -p, -s, -t and -w need the script to be installed (at the same time or earlier) and will simply be ignored if it is not.

To clear the boolean options -a, -n and -s (and also -t), put them in a comma separated -w list, without the leading dashes, e.g. '-w a,s,t' (or '-wa,s,t').

Special options

These are not mentioned in the help screen. Their use is explained in other parts of this document. This is just a summary.

	--force        force the script to handle the plugin in spite of other sources
	--no-auth      download the package list without authenticating it
	--release=NAME download the plugin package from an Ubuntu repository
	--remove-fpp   remove the obsolete freshplayer plugin related files
	--remove-pfnf  remove pepperflashplugin-nonfree
	--update-keys  update or check the public keys for the Ubuntu archives
	-Drun          install the script automatically, when using 'get'

The first two are stored after they have been used once and need -w to clear them. The third one can be cleared like that as well, but also by specifying the option without an argument or with an empty one (i.e. --release=).

Functions

The main functions are:

For anything other than displaying the help text or status information, the script must run as root.

Install the script and the plugin

Unpack the tarball somewhere convenient, e.g. using your filebrowser's 'Extract here' function. This will create a directory pf-wrapper containing:

	  lib/pf-wrapper/functions
	  lib/pf-wrapper/history
	  lib/pf-wrapper/install
	  lib/pf-wrapper/README
	  lib/pf-wrapper/ubuntu-keyring-2004-archive.gpg
	  lib/pf-wrapper/ubuntu-keyring-2012-archive.gpg
	  lib/pf-wrapper/WARNING
	  pf-wrapper
	  install
	  replacer

Open a terminal window on that directory and run one of the commands mentioned above. Use sudo ./pf-wrapper install or ./install to do a 'quick install' of the script and the plugin. This will set the options -a, -c, -i, -n, -s and -t 3600 (i.e. one hour) and the special --remove-* options. You can change the settings afterwards if they do not suit you.
If necessary, use sudo pf-wrapper status to check everything is set up the way you want.

While the -i option will cause the extracted contents of the tarball to be moved to /usr/local/sbin and .../lib, the tarball itself will stay where you put it.

Install or update the plugin

If you do not want to 'install' the script, you can still use it to install or update (or remove) the Pepper Flash plugin. You can run it with sudo ./pf-wrapper plugin from the directory it is in. This will just retrieve the plugin and put it where the browser can find it. Updating an already installed plugin works the same way.

The script needs the 'functions' file whether it is installed or not, so make sure this is in the lib/pf-wrapper directory.

If you used the special option --release, the ubuntu-keyring files are also required. If they are missing, the script can still check for updates, but only if the special option --no-auth is given. This will switch off the authentication of the package list, which is not recommended.

If you want to 'install' the script as well, run sudo ./pf-wrapper -i plugin. Use sudo ./pf-wrapper -i if you want to install the script itself first and handle installation of the plugin later, for instance after you have checked out the other options.

Remove selectively

Use sudo pf-wrapper remove to remove the plugin. If you also want to remove the cron job, add the -r option and to uninstall the script as well, add -u. If you do not want to remove the plugin but just remove the cron job or uninstall the script, sudo pf-wrapper -r or sudo pf-wrapper -u should do it.
Uninstalling the script will actually delete the script itself and its support files from /usr/local/sbin and /usr/local/lib, so if you do not have another copy elsewhere or kept the tarball, you will have to download everything again.
If you add the -p option, all other files and directories related to the script will be deleted as well.

Remove everything

An alternative way to remove the installed script and plugin in one go, is sudo pf-wrapper purge. Be aware this will delete everything the script installed without question or warning!

Show some status information

The output of sudo pf-wrapper status (or ./pf-wrapper status from inside the /usr/local/sbin directory) could look similar to this:

	script              : version 2.2.0 (2016-11-02) installed in /usr/local/sbin
	- currently running : /usr/local/sbin/pf-wrapper v2.2.0 (2016-11-02)
	- library           : /usr/local/lib/pf-wrapper
	- version check     : 2.2.0
	- state information : stored in /var/local/pf-wrapper/state
	cron job            : installed in /etc/cron.daily
	- update plugin     : yes
	- update script     : yes
	- notifications     : yes
	notification timeout: 3600 seconds
	freshplayer plugin  : /usr/lib/mozilla/plugins/flash-mozilla.so =>
	 /usr/lib/browser-plugin-freshplayer-pepperflash/libfreshwrapper-flashplayer.so
	Pepper Flash plugin : 23.0.0.205 in /usr/lib/PepperFlash
	- forced handling   : no
	- other sources     : none
	packages to install : none

This shows a more or less default installation, which could be the result of a sudo ./pf-wrapper install, i.e. a 'quick install'. If you specified --release=yakkety (or upgraded the script from version 2.1.0), this could be shown as well:

	source package      : adobe-flashplugin_1:20161026.1-0ubuntu0.16.10.1_amd64
	distribution release: yakkety
	skip authentication : no
	key file(s) + hash  : 
	/var/local/pf-wrapper/apt/etc/apt/trusted.gpg.d/ubuntu-keyring-2004-archive.gpg
	 - SHA256: 36339818f778643728e834ebc899f3ad339fc2a43c121fa4426b6fc0571e3bba
	/var/local/pf-wrapper/apt/etc/apt/trusted.gpg.d/ubuntu-keyring-2012-archive.gpg
	 - SHA256: 5321d780da31a1fa35c044470ef849a2f6244048855fdc4c22e527b6366a0ef7
	/usr/local/src/lib/pf-wrapper/ubuntu-keyring-2004-archive.gpg
	 - SHA256: 36339818f778643728e834ebc899f3ad339fc2a43c121fa4426b6fc0571e3bba
	/usr/local/src/lib/pf-wrapper/ubuntu-keyring-2012-archive.gpg
	 - SHA256: 5321d780da31a1fa35c044470ef849a2f6244048855fdc4c22e527b6366a0ef7

If 'other sources' doesn't say 'none', the script has found another source for the Pepper Flash plugin and should refuse to update it itself. Unless that other source is pepperflashplugin-nonfree, of course.

Download a new version of the script

Every time the script is run, it checks the DNS for the hostname pfw-app on the domain of this website. The result should be an IP address in the range 10.x.x.x (one of the private ranges). If the x.x.x bit represents a version number which is higher than the script's own number, it will assume a new version is available and warn you about it. You can download that new version with the command sudo pf-wrapper get (or just visit this site and pick up the tarball - your choice).

If you have installed the script with the -c and -s options, it will do this upgrade itself and let you know about it through the notification system (provided you have used the -n option). If you have not used -s, it will simply let you know (unless you have not used -n either).

After you have used the 'get' command, both the downloaded tarball and the pf-directory with contents will end up in /tmp/pf-wrapper.<LARGE NUMBER>. You can start the installation from there, but you cannot expect to keep the files there indefinitely, as /tmp will usually be erased when your machine (re)boots.
During normal operation, the script may clear its temporary directory as well, by the way.

Running the 'get' command with the option -Drun will make the script install itself automatically after downloading. This will be a limited installation, with the -i option only, just to move the script's files out of the temporary directory, but any persistent options that have been set previously should be preserved.

Upgrade errors

Upgrading the script can fail. The most common errors are:

Error messageProbable cause
Could not retrieve tarballserver error
Could not retrieve signature fileserver error
Could not retrieve checksum fileserver error
BAD signature for downloaded tarballupload error
sha256 checksum of downloaded tarball incorrectupload error
Downloaded version is not newerupload error (or user error - did you try to download a new version when there was none?)

Server or upload errors may well be temporary problems. If trying again later does not help, please contact me.

The log or terminal can also show the message Could not verify signature for downloaded tarball. This should not block installing the new version (as long as one of the last two errors does not apply as well), but you may want to prevent it from showing up again by adding the required public GPG key: gpg --keyserver keys.gnupg.net --recv-keys 0xE18CE6625CB26B26. If that command produces an error, try one of the servers from this page.
The key may already be available on your system, in apt's keyring. In that case the script will try to import it from that keyring.

Debugging

The script has a number of debugging functions, all starting with the -D option switch. Currently they are not documented, but this may change in future.

Upgrading from 1.x.x versions

This section is left in for reference. It no longer applies, as the current version of the script does not handle upgrading from these older versions at all (the tarball does not contain the necessary symbolic link, so the old version's upgrade function will fail to find the install script). The special option --remove-fpp mentioned below still works though, so the paragraphs about the freshplayer plugin may still be useful.

Versions of the script before 2.0.0 did not have a separate option to set auto-upgrading of the script. If the -a option had been set, the script would be upgraded automatically as well. However, it was easy to miss that using that option would have this effect. Upgrading from such a version is done through an intermediary script, which asks the user if they want to accept the new version and offers several other options as well.
Selecting 'Install' essentially runs the upgrade as a 'quick install'. It is possible to abort the automated run and do the upgrade manually. In that case, what to do about the freshplayer plugin becomes an issue.

The freshplayer plugin (old script installed)

The current version of the script no longer handles installing and updating the freshplayer plugin. If you do a 'quick install' and the script detects the old setup, it will automatically remove the files involved and install the Debian package browser-plugin-freshplayer-pepperflash, which provides that plugin.

If you use the 'plugin' command, you can force the same behaviour with the special option --remove-fpp. If you do not add this option, you will be asked whether you want to make these changes.
Not removing those files is not recommended. They will no longer be maintained in any way and may cause conflicts if you decide to install the freshplayer plugin's package at a later date.

Should you want to install that package manually on a machine with Debian jessie, keep in mind it is in the backports repository for that distribution, so you would need to add -t jessie-backports to the apt-get install command. On Ubuntu ot later versions of Debian the command would be something like sudo apt-get install --no-install-recommends browser-plugin-freshplayer-pepperflash. The --no-install-recommends option is necessary to avoid dragging pepperflashplugin-nonfree back in.

The freshplayer plugin (old script NOT installed)

If you used an older version of the script to install the freshplayer plugin but did not install that script itself, the current version cannot reliably determine whether the plugin can be removed. It may have been installed by some other means. In that case, you should add the special option --remove-fpp to the command if you want the plugin removed.
You can use (just) that option any time, by the way, even after you have installed the current version of the script, for instance if you chose not to let it remove the old setup at that time.

Using an Ubuntu package

By default, the script will download version information and the tarball with the plugin from Adobe's own website. Unfortunately Adobe does not provide a GPG signature or any other way to verify the download. If you do not like that, you can instruct the script to download the adobe-flashplugin package from Canonical's Partner repository and extract the plugin from it (the package will not be installed on your system). In that case, you should have a little more certainty that the file you download comes from a verified source.
[By the way, this was the default for version 2.1.0 of the script. Old settings will not be changed automatically!]

Use the special option --release with the name of the Ubuntu release (only the first part, e.g. --release=yakkety for Yakkety Yak), either in combination with another command or on its own. Of course this setting is only remembered if the script is installed.
Be careful to spell the name correctly. The script assumes you know what you are doing and does not try to verify the release name even exists.

If you use the option without argument, the script will switch back to using Adobe's website.

Updating the public keys

The public keys for the Ubuntu Archive, used to verify the adobe-flashplugin package download, are supplied with the script. There is a small chance Flash is still not fully dead by the time they need to be updated (if ever). A new version of this script's 'package' should be made available with the new keys. In case that does not happen or not quickly enough, you can update the keys yourself by running the script with the special option --update-keys. You can also use that to confirm the version of the keys supplied with the script correspond with the ones in the Ubuntu keyring package.

Updating the Ubuntu release

Ubuntu releases have a limited lifespan. Once the Yak is dead, you will need to switch to another release. Simply use the special option --release again, with the name of the new release. Of course if you use the most recent LTS release, Xenial Xerus, you have until April 2021 before that becomes an issue.

Logging

The script produces some logging in /var/log/pf-wrapper.log and /var/log/syslog should get an entry whenever the cron job calls the script.

Additional notes

Firefox apparently does not always notice the plugin version has changed, so it will report the wrong version on the Add-ons/Plug-ins page. If this happens, I have found the only certain way to get Firefox to notice the change, is by closing it and deleting the pluginreg.dat file in the profile directory.

Also, this: NPAPI Plugins in Firefox.

Disclaimer

As far as I am aware, this script does what it is supposed to do. Nevertheless, you use it entirely at your own risk. That said, if you find a bug, do get in touch with me so I can fix it...

Licence

This script is provided under the EUPL, version 1.1, which is a FOSS licence, compatible with GPLv2.


Miscellaneous

About design decisions and 'technical notes'...

The script was written for Debian and related distributions. I did not put it in a Debian package, because I initially wrote it as something that should be useable on any Linux system. It quickly became clear that was not realistic, but I kept the tarball, because it is simpler than Debian packaging.

The original target was the freshplayer plugin. When I created the first version of the script, early 2015, there was only a package for Ubuntu. When the package for Debian showed up a couple of months later, I was not sure its releases would keep up with upstream (they did not, at first...). So I did not change the script until that seemed to improve.
I am not sure how long this incarnation of the script will remain available. If pepperflashplugin-nonfree had been able to keep track of plugin updates, it probably would have disappeared already...

The freshplayer plugin versions of the script built that plugin from source, so a considerable number of development tools and packages was required. Currently, only these packages are needed and will be installed if not present:

	bsdutils
	coreutils
	cron
	gnupg
	grep
	libnotify-bin
	sed
	wget

Most (if not all) of these should already be installed on any Linux system, so checking for them is really just a formality. As checking for and installing these packages requires a package management system anyway, checking for dpkg and apt would not make much sense.

If zenity is available, the script can present some of its files, like the README, in a neat(ish) graphical window (pf-wrapper -Dz-rm should give an idea).
The 2.0.x versions did that when auto-upgrading from an old style script. Without zenity, the terminal was the only option there. A notifcation was used to warn the user about it. Making the script install a missing zenity automatically seemed like a bad idea, because the user may not have liked a lot of GTK+ stuff pulled in for just one application, especially as that would have been for one time use only...

Files and directories created and/or used by the script:

	/etc/cron.daily/pf-wrapper      daily cron job file
	/etc/logrotate.d/pf-wrapper     log rotation specification
	/tmp/pf-wrapper.<LARGE NUMBER>  temporary scratch directory
	/usr/local/lib/pf-wrapper/      the script's library (see above for contents)
	/usr/local/sbin/pf-wrapper      the script after installation
	/var/local/pf-wrapper/          variable data
	/var/log/pf-wrapper.log         log file

partner-hypothetical