layman makes it easy to retrieve and update overlays for Gentoo. In addition it makes it TRIVIAL to break your system.

The Gentoo main tree provides you with high quality ebuilds that are all maintained by Gentoo developers. This will not be the case for most of the overlays you can get by using layman. Thus you are removing the security shield that the standard tree provides for you. You should keep that in mind when installing ebuilds from an overlay.

To ensure the security of your system you MUST read the source of the ebuild you are about to install.

List of possible layman actions.

List of available layman path options.

List of layman output options.

layman now supports multiple database types for layman’s install file. The options allowed include: xml, json, and sqlite. While xml is the default database type you may migrate from one database type to the other using the layman-updater tool while supplying the -m flag, followed by the database type you’d like to use.

layman now accepts multiple repository config file options. One being the already standard make.conf option and the other being the repos.conf files that can be placed in /etc/portage/repos.conf/. The below configuration options allow you to alter particular things regarding the repository configuration::

layman allows you to fetch an overlay without the need to modify any configuration files. In order for this to be possible the script needs an external list of possible overlay sources. There is a centralized list available at https://api.gentoo.org/overlays/repositories.xml but nothing will prevent you from using or publishing your own list of overlays. The location of the remote lists can also be modified using the --overlays option when running layman.

To get a new overlay added to the central list provided for layman, send a mail to <overlays@gentoo.org>. Gentoo developers may add their overlay entries directly into the list which can be accessed over the CVS repository for the Gentoo website.

You can also use several lists at the same time. Just add one URL per line to the overlays variable in your configuration file. layman will merge the contents of all lists.

layman also allows you to define local files in this list. Just make sure you prepend these path names in standard URL notation with file://. layman also gives you the ability to just add an overlay definition to /etc/layman/overlays/some-overlay.xml and it will be automatically available for actions such as add, delete, info… (see below for file format details)

If you need to use a proxy for access to the Internet, you can use the corresponding variable in the layman configuration file. layman will also respect the http_proxy environment variable in case you set it.

When adding an overlay or updating its source URL you can specify which protocols you wish to use. Examples of this include http://, git://, and https://.

To filter these protocols on a system-wide level you may alter the protocol_filter variable in your layman configuration file.

Otherwise, you may specify which protocols you would prefer to be filtered out on a per-run basis using the --protocol_filter flag.

Using this filtering will ensure that no other protocols other than the ones specified will be used. Meaning that if an overlay does not support any of the specified protocols, it will not install.

layman stores a local copy of the fetched remote list. It will be stored in /var/lib/layman/cache.xml by default. There exists only one such cache file and it will be overwritten every time you run layman.

Since layman is designed to automatically handle the inclusion of overlays into your system it needs to be able to modify the PORTDIR_OVERLAY variable in your /etc/portage/make.conf file. But /etc/portage/make.conf is a very central and essential configuration file for a Gentoo system. Automatically modifying this file would be somewhat dangerous. You can allow layman to do this by setting the make_conf variable in the configuration file to /etc/portage/make.conf.

A much safer and in fact recommended solution to the problem is to let layman handle an external file that only contains the PORTDIR_OVERLAY variable and is sourced within the standard /etc/portage/make.conf file. Just add the following line to the end of your /etc/portage/make.conf file:

source /var/lib/layman/make.conf

/var/lib/layman/make.conf is the default provided in the layman configuration. Change this file name in case you decide to store it somewhere else.

The file does not necessarily need to exist at the beginning. If it is missing, layman will create it for you.

There is also no need to remove the original PORTDIR_OVERLAY variable from the make.conf file. Layman will simply add new overlays to this variable and all your old entries will remain in there.

Once a remote list of overlays has been fetched, layman allows to add overlays from the remote list to your system. The script will try to fetch the overlay. If this is successful the overlay information will be copied from the cache to the list of locally installed overlays. In addition layman will modify the PORTDIR_OVERLAY variable to include the new overlay path.

Removing the overlay with layman will delete the overlay without leaving any traces behind.

In order to update all overlays managed by layman you can run the script with the --sync ALL option or the --sync-all flag.

portage will find installed overlays via your repo config files, whether it be make.conf or repos.conf. If you wish to hide the overlay from portage so that the ebuilds will not be accessible then you can do so with the --disable OVERLAY option. This will then disable the overlay in your repo configurations.

To re-enable them again so that portage can again access the ebuilds of that overlay you can simply do so with the --enable OVERLAY option.

layman provides the -L, --list and -l, --list-local options to print a list of available respectively installed overlays.

Listing will prepend all fully supported overlays with a green asterisk, all non-official overlays with a yellow asterisk and all overlays that you will not be able to use since you do not have the necessary tools installed with a red asterisk.

In the default mode layman will be strict about listing overlays and only present you with overlays that are fully supported. In addition it will complain about overlays that are missing a description field or a contact attribute. This type of behavior has been added with layman 1.0.7 and if you’d like to return to the old behavior you may use the k option flag or set the nocheck option in the configuration file.

You can search through the ebuilds available in the overlays on http://overlays.gentoo.org/ by using eix. Emerge the package and run:

update-eix-remote update

Alternatively, you can browse overlays that you have not installed on http://gpo.zugaina.org/.

Currently layman supports overlays that are exported via rsync, CVS, subversion, bzr, darcs, git, mercurial, tar packages, or squashfs images that will be mounted read-only. It also supports the generated overlay type g-sorcery installed with the g-cran package (at time of this writing, only available in the science overlay).

Layman uses a central list of overlays in XML format. The file looks like this:

Example 1. An example overlays.xml file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="official">
    <name>gnome</name>
    <description>experimental gnome ebuilds</description>
    <homepage>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=summary</homepage>
    <owner type="project">
        <email>gnome@gentoo.org</email>
        <name>GNOME herd</name>
    </owner>
    <source type="git">git://git.overlays.gentoo.org/proj/gnome.git</source>
    <source type="git">http://git.overlays.gentoo.org/gitroot/proj/gnome.git</source>
    <source type="git">git+ssh://git@git.overlays.gentoo.org/proj/gnome.git</source>
    <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=atom</feed>
    <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=rss</feed>
</repo>
</repositories>

Example 2. An example overlays.xml file with a branch

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="official">
    <name><hardened-development></name>
    <description><Development Overlay for Hardened Gcc 4.x Toolchain></description>
    <homepage>http://git.overlays.gentoo.org/gitweb/?p=proj/hardened-dev.git;a=summary</homepage>
    <owner type="project">
       <email>hardened@gentoo.org</email>
    </owner>
    <source type="git" branch="uclibc">git://git.overlays.gentoo.org/proj/hardened-dev.git</source>
    <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/hardened-dev.git;a=atom</feed>
</repo>
</repositories>

Users can specify a branch for an overlay, given one actually exists. This logic is applicable to CVS overlays as well and the branch variable is comparable to specifying a subpath for a CVS repository.

Simply create an overlay list in the format described above and run layman with the -o switch. You need to prepend local file URLs with file://. New is the ability to just add an overlay definition like the above to /etc/layman/overlays/some-overlay.xml and it will be automatically available for actions such as add, delete, info…

The global list of overlays used by layman lies at https://api.gentoo.org/overlays/repositories.xml.

All Gentoo developers have access to this location via CVS and can modify the list of overlays.

If you are not a Gentoo developer but wish to get your overlay listed you should contact the Gentoo Overlays team at <overlays@gentoo.org>. You can also join #gentoo-overlays on irc.freenode.net.

layman -f -a wrobel

This would add the overlay with the id wrobel to your list of installed overlays.

layman -s ALL

This updates all overlays

layman -f -a wrobel webapps-experimental

This fetches the remote list and immediately adds two overlays