Third party repository usage

Note:
This documentation has moved to a new home! Please update your bookmarks to the new URL for the up-to-date version of this page.

Ubuntu is an operating system with thousands of packages and snaps available to its users, but it is humanly (and sometimes technically!) impossible to make all software out there available in the official repositories. There are situations where you may want to install a package that is not maintained by Ubuntu, but is maintained by a third party entity. We don’t recommend using third party APT repositories, but we know that users sometimes have no other option – so let’s take a look at some of the pitfalls, alternatives, and mitigations.

Why not use third party APT repositories?

While having access to the software you want to use is great, it is crucial to understand the risks involved in using third party APT repositories.

Security risk

When using any software that you have not audited yourself, you must implicitly trust the publisher of that software with your data. However, with third party APT repositories, there are additional implications of this that are less obvious.

Unlike more modern packaging systems, APT repositories run code that is not sandboxed. When using software from more than one publisher, such as from your distribution as well as a third party, APT and dpkg provide no security boundary between them.

This is important because in addition to trusting the publisher’s intentions, you are also implicitly trusting the quality and competence of the publisher’s own information security, since an adversary can compromise your system indirectly by compromising the software publisher’s infrastructure.

For example, consider users who use applications such as games where system security isn’t much of a concern, but also use their computers for something more security-sensitive such as online banking. A properly sandboxed packaging system would mitigate an adversary compromising the game publisher in order to take over their users’ online banking sessions, since the games wouldn’t have access to those sessions. But with APT repositories, the game can access your online banking session as well. Your system’s security – as a whole – has been downgraded to the level of the app publisher that has the worst security; they may not consider their information security important because they aren’t a bank.

System integrity

Even if you are certain that the third party APT repository can be trusted, you also need to take into account possible conflicts that having an external package may bring to your system. Some third party packagers – but not all – are careful to integrate their packages into Ubuntu in a way that they don’t conflict with official packages from the distribution, but it is technically impossible to predict future changes that might happen in future Ubuntu releases. This means that fundamentally there always is the possibility of conflict. The most common cause of system upgrade failure is the use of third party repositories that worked at the time but later conflicted with a subsequent upgrade.

One of the most common conflicts occurs when a third party package ships with a file that is also shipped by an official Ubuntu package. In this case, having both packages installed simultaneously is impossible because dpkg will prevent managed files from being overwritten. Another possible (and more subtle) issue can happen when the third party software interacts in a problematic way with an official package from Ubuntu. This can be harder to diagnose and might cause more serious problems in the system, such as data loss and service unavailability.

As a general rule, if the third party package you are installing is interacting with or is a modified version of an existing Ubuntu package, you need to be more careful and do some preliminary research before using it in your system.

Lack of official Ubuntu support

If you decide to install a third party package on your Ubuntu system, the Ubuntu community will struggle to offer support for whatever failures you may encounter as a consequence, since it is out of their control and they are unlikely to be familiar with it. In fact, if you experience a bug in an official Ubuntu package but it is later determined that the bug was caused by a third party package, the Ubuntu community may not be able to help you.

In other words, if you use a third party software you will have to contact its packagers for help if you experience any problem with it.

A better solution to third party APT repositories: snaps

As we have seen, third party APT repositories are not simple and should be handled carefully. But there is an alternative that is natively supported by Ubuntu and solves some of the issues affecting third party APT repositories: snaps.

Due to the way they are architected, snaps already carry all of their dependencies inside them. When they are installed, they are placed in an isolated directory in the system, which means that they cannot conflict with existing Ubuntu packages (or even with other snaps).

When executed, a snap application is sandboxed and has limited access to the system resources. While still vulnerable to some security threats, snaps offer a better isolation than third party APT repositories when it comes to the damage that can be done by an application.

Finally, if a snap is published in the snapstore, you will not need to go through the hassle of modifying sources.list or adding a new GPG key to the keyring. Everything will work “out of the box” when you run snap install.

Mitigating the risks

If the software you want is not available as a snap, you may still need to use a third party APT repository. In that case, there are some mitigating steps you can take to help protect your system.

Security risk mitigation

• If the package you want to install is Free Software/Open Source, then the risk can be reduced by carefully examining the source code of the entire software, including the packaging parts. The amount of work required to do this assessment will depend on the size and complexity of the software, and is something that needs to be performed by an expert whenever an update is available. Realistically, this kind of evaluation almost never happens due to the efforts and time required.
• The availability and cadence of fixes to security vulnerabilities should also be taken into account when assessing the quality and reliability of the third party APT repository. It is important to determine whether these fixes are covered by the third party entity, and how soon they are released once they have been disclosed.
• In addition, you must ensure that the packages are cryptographically signed with the repository’s GPG key. This requirement helps to confirm the integrity of the package you are about to install on your system.

System integrity mitigation

• Avoid release upgrades whenever possible, favouring redeployment onto a newer release instead. Third party APT repositories will often break at release time, and the only way to avoid this is to wait until the maintainers of the repository have upgraded the software to be compatible with the release.
• Configure pinning (we show how to do this below). Pinning is a way to assign a preference level to some (or all) packages from a certain source; in this particular case, the intention is to reduce the preference of packages provided by an external repository so that official Ubuntu packages are not overwritten by mistake.

Dealing with third party APT repositories in Ubuntu

Now that we have discussed the risks and mitigations of using third party APT repositories, let’s take a look at how we can work with them in Ubuntu. Unless otherwise noted, all commands below are to be executed as the root user (or using sudo with your regular user).

Add the repository

Several third party entities provide their own instructions on how to add their repositories to a system, but more often than not they don’t follow best practices when doing so.

Fetch the GPG key

The first step before adding a third party APT repository to your system is to fetch the GPG key for it. This key must be obtained from the third party entity; it should be available at the root of the repository’s URL, but you might need to contact them and ask for the key file.

Although several third party guides instruct the user to use apt-key in order to add the GPG key to apt’s keyring, this is no longer recommended. Instead, you should explicitly list the key in the sources.list entry by using the signed-by option (see below).

Third party APT repositories should also provide a special package called REPONAME-archive-keyring whose purpose is to provide updates to the GPG key used to sign the archive. Because this package is signed using the GPG key that is not present in the system when we are initially configuring the repository, we need to manually download and put it in the right place the first time. Assuming that REPONAME is externalrepo, something like the following should work:

wget -O /usr/share/keyrings/externalrepo-archive-keyring.pgp https://thirdpartyrepo.com/ubuntu/externalrepo-archive-keyring.pgp

Sources.list entry

To add a third party APT repository to your system, you will need to create a file under /etc/apt/sources.list.d/ with information about the external archive. This file is usually named after the repository (in our example, externalrepo). There are two standards the file can follow:

• A one-line entry, which is the most common. In this case, the extension of the file should be .list.
• The deb822 format, which is more descriptive but less common. In this case, the extension of the file should be .sources.

An example of a one-line entry would be the following:

deb [signed-by=/usr/share/keyrings/externalrepo-archive-keyring.pgp] https://thirdpartyrepo.com/ubuntu/ jammy main

An example of a deb822 file for the same case would be the following:

Types: deb
URIs: https://thirdpartyrepo.com/ubuntu
Suites: jammy
Components: main
Signed-By: /usr/share/keyrings/externalrepo-archive-keyring.pgp

There are cases when the third party APT repository may be served using HTTPS, in which case you will also need to install the apt-transport-https package.

After adding the repository information, you need to run apt update in order to install the third party packages. Also, now that you have everything configured you should be able to install the externalrepo-archive-keyring package to automate the update of the GPG key.

Configure pinning for the repository

In order to increase the security of your system and to prevent the conflict issues discussed in the “System integrity” section, we recommend that you configure pinning for the third party APT repository.

You can configure this preference level by creating a file under /etc/apt/preferences.d/ that is usually named after the repository name (externalrepo in this case).

In our example, a file named /etc/apt/preferences.d/externalrepo should be created with the following contents:

Package: *
Pin: origin thirdpartyrepo.com
Pin-Priority: 100

There are several levels of pinning you can choose here; the Debian Reference guide has good documentation about the topic. The level 100 used above means that users will be able to install packages from the repository and that automatic package upgrades are also enabled. If you want to be able to install packages but don’t want them to be considered for automatic upgrades, you should use the level 1.

How to remove a repository

If you have enabled a third party APT repository but found yourself in a situation where you would like to remove it from the system, there are a few steps you need to take to make sure that the third party packages are also uninstalled.

The first step is to remove the files created in the steps above. These are:

• The sources.list file, under /etc/apt/sources.list.d/.
• The package pinning preference, under /etc/apt/preferences.d/.
• If the third party APT repository does not provide the GPG key in a package, then you can also remove it manually from /usr/share/keyrings/.

Before you run apt update, you might want to also remove the third party packages that were installed from the repository. The following one-liner will list all those packages:

apt remove --purge \
    $(grep "^Package: " /var/lib/apt/lists/#<SELECT_THE_FILE_FOR_YOUR_REPOSITORY>#_*_Packages \
        | cut -d " " -f2 | sort -u | \
        xargs dpkg-query -W -f='${binary:Package}\t${db:Status-Abbrev}\n' 2> /dev/null | \
        awk '/\tii $/{print $1}')

Make sure to replace #<SELECT_THE_FILE_FOR_YOUR_REPOSITORY># with the right file for the third party APT repository.

After that, you can safely run apt update.

A special case: Ubuntu PPAs

Ubuntu PPAs can be considered as a special case of third party APT repositories. In fact, there are upstream projects that choose to ship their software through PPAs because of the existing tooling that allows users to easily add them to their Ubuntu systems.

It is important to mention that the same points raised above regarding security, system integrity and lack of official Ubuntu support also apply to PPAs.

If you would like to install packages from a PPA, first you will need to add it to your system. For that, you can use the add-apt-repository command. Suppose you want to add a PPA from user thirdparty named externalrepo. You can run:

add-apt-repository ppa:thirdparty/externalrepo

This command will automatically set up the GPG key, as discussed above. After that, you can run apt update and install the third party packages provided by the PPA. Note that add-apt-repository will not adjust the repository pinning, so it is recommended that you go through that process manually.

If you decide you do not want to use the PPA anymore and would like to remove it (and its packages) from your system, the easiest way to do it is by installing the ppa-purge package. You can then execute it and provide the PPA reference as its argument. In our example, that would be:

ppa-purge ppa:thirdparty/externalrepo