Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.


It should be possible to install software in a safe and supported way over a website. This allows us to provide more dynamic content and richer metadata (like screenshots, comments) than with traditional client applications and to better support Launchpad's new personal package archives. To achieve this, a new "apt://" protocol will be created that allows giving commands to apt/synaptic.

Release Note

The apt-firefox-archive-plugin feature allows users to install software via simple websites in a safe and supported way.


People use to install software just clicking on a URL. Softonic, Tucows and others, list lots of applications that users can easily add to their Windows boxes. The linux way is not that easy.

An Ubuntu distribution has got a defined repository with loads of software, but users need to use a specific software installer (gnome-app-install, synaptic) to add more software.

Use Cases

  • Alfonso is asking a question on the Guadalinex forums. A support technician from Guadalinex team founds that his problem can be resolved by installing a single package. He posts an answer with a link to apt://unrar, and the user only has to click on it to solve his problem.

  • The Guadalinex team needs to provide their users with an up-to-date list of "extra software" which doesn't fit on the CD. The developers add a menu entry in the stable version of the distro that opens a webpage hosted on Guadalinex servers that can be easily updated, with links to apt://name_of_package

  • Pepe, an Ubuntu enthusiast, wants to write a Beryl HOWTO in his weblog. He easily adds links to the referred software with "apt://name-of-package" urls.

  • Celso has a launchpad PPA for his software. He wants to make it easy to add his repository and puts an apt protocol handler in for this.


The apt protocol should support the following actions:

  • install package from existing repository
  • adding new repository


The default internet browser will call a external application whenever an apt:package_name url is clicked. It adds the complete url as an argument to that external application. The external application will then do the equivalent of apt-get install $package_name (using synaptic or adept_batch as its backend)

The new protocol will follow http://tools.ietf.org/html/rfc3986 (STD66).

In its easiest from, the new url will be formatted:


We are not linking a .deb file, just giving the name of the package to an external application. By default the syntax will be not hierarchical, but to stay compatible with Guadalinex a hierarchical argument will be supported as well (apt://pkg_name will also work).

In addition to this, a syntax will be supported to install applications that come from repositories that are not in the current sources.list. This synatx will follow the following style:


The keyfile will be searched in /usr/share/app-install/channels. If no keyfile is given it is assumed that the repository is authenticated with the default key. If the repository can not be authenticated it will not be added and no packages get installed.

If the repository is not already in the sources.list the UI will ask if the repository should be added permanently or just temporarily. The package is then installed. If no parameter is given it is assumed that the distro is set to "/". The line above expands to:

deb http://launchpad.net/~mvo/ppa/test/ /

The parameters "dist=foo" and multiple "section=bar" are supported as well. So apt+http://launchpad.net/~mvo/ppa/test/?package-my-new-pkg?dist=feisty?section=foo?section=bar expands to a sources.list line like this:

deb http://launchpad.net/~mvo/ppa/test feisty foo bar

Additional a parameter minversion=x.y will be supported. This enables us to build webpages about packages that describe new features and provide a quick "install now" link. If (for some reason) the minversion is not available the user will not be disappointed that the package he installed does not actually support the advised features.




  • Firefox (and in the future other browsers like konqueror and
    • epiphany) must be tweaked to recognize a new apt:// protocol.

  • When an apt: url is clicked a python application is
    • triggered. The browser will pass the url to this application.
  • The application will display a dialog explaining what is going to happen
    • and how much download is required. If the user confirms it will call synaptic or adept_batch (depending on the desktop environment) with a few parameters to download and install the package, including dependencies (/usr/sbin/synaptic --hide-main-window --non-interactive --set-selections-file /tmp/apt-packagename.tmp)

The handler will be installed into /usr/share/firefox/defaults/prefs/apt-archive-handler.js as an additional configuration file. The whole application will done as a new package with some python clue code (gapti/gdebi will be reused as much as possible or even merged if that is feasible).

A similar mechanism is implemented in Guadalinex, the file /usr/lib/firefox/firefox.cfg was modified to achieve the same goal, and a perl script was added to parse the url, and call synaptic. We will provide compatibility with their syntax.

The current set of commands is limited on purpose. Actions like "update", "upgrade", "dist-upgrade", "remove" look not useful or plain dangerous. We may expand the syntax later to support multiple packages separated by ",".


With the above design the security implications are small. All software comes from trusted repositories, it is only possible to add repositories that have a keyfile that is already available in ubuntu already (e.g. in the app-install-data-commercial package).

A possible attack vector would be to trick users to install a application with a known vulnerability or to install applications that open a port.

Future Work

The approach to allow only adding repositories with already available keys limits this protocol for third party vendors. We could consider extending the specification in the future to have a command like "add-repository-unsafe" if that is a desired goal, or have a new apt-protocol: handler.

Releated Work

A similar approach using a command file instead of a protocol: https://wiki.ubuntu.com/ThirdPartyApt and https://wiki.ubuntu.com/GAptI.

The svn for the Guadalinex implementation:

svn co http://forja.guadalinex.org/guadalinexv4/apps/xapi


  • KillerKiwi - Just about died when I saw this almost exactly what I proposed for edgy... https://wiki.ubuntu.com/aptgetinstallprotocol . Thanks for implementing this Smile :) BTW register the protocol in Gconf and it will be available for all gnome apps including firefox and thunderbird One last thing I think would work better integrated with gnome-app-install rather than gdebi

    • RafaelProenca - It don't make use of gdebi. But indeed, using g-a-i like in this screenshot would be better than just a simple "Yes & No" dialog.

    • KillerKiwi- That screen shot is exactly what I meant Wink ;) (Not sure where I got the idea gdebi was being used). Maybe add to the top "Official Ubuntu Software" or "Third Party Unsupported Software"... the exact phrase (Maybe copy the software sources dialogue) may need tweaking but you get the idea, some way to easily tell this is official Ubuntu or not.

    • Cyphase - I agree with KillerKiwi (I was just coming here to comment on it). If you just add a GConf key under /desktop/gnome/url-handlers, all Gnome supporting browsers will be able to act on the apt:// protocol.

    Gaurish Sharma - Does it support multiple packages at once? If not then please include this feature

    AlfonsoDeCala - This implementation must take care of many "apt" links clicked simultaneously. We (Guadalinex) have a web interface showing a software catalogue and I'm afraid users try to click some of them very quickly. A repository lock should be checked (and user informed) ASAP.

    Glaydson - I created a open source project that read the sources.list and make a structure to use apt protocol in http://www.apturl.net.

The current set of commands is limited on purpose. Actions like "update", "upgrade", "dist-upgrade", "remove" look not useful or plain dangerous. We may expand the syntax later to support multiple packages separated by ",".

  • I don't see any reason to limit this. Allow removing packages, adding repositories, etc. Prevent people from doing dangerous things by clearly explaining to them what they are about to do and what the dangers are, not by intentionally crippling software and making things artificially difficult. This isn't like downloading an .exe file from a Flash pop-up that mimics Windows and letting it do whatever it wants to your hard drive. Anything done through an apt: URL has to go through the gateway of the AptURL program first, which allows us to control exactly what the user sees when they try to do it.
  • Clorox - So the AND operator is implemented by a comma, but there needs to be an OR operator. This way, if a package doesn't work, then the next package should be tried. For example, apt:adobe-flashplugin|flashplugin-installer will try to install adobe-flashplugin at first, then fall back to flashplugin-installer if that doesn't work.

    Also, since apt+http:// is used for the protocol, there also needs to be apt+ftp:// (because some repositories use that instead) and apt+mirror:// (because apt recognizes it, and Playdeb uses it).


AptFirefoxFileHandler (last edited 2009-07-22 05:47:36 by claysmalley)