Gentoo Wiki


This article is part of the Tips & Tricks series.
Terminals / Shells Network X Window System Portage System Filesystems Kernel Other



Portage provides the possibility of maintaining private overlays which is a great way for incorporating self-written, modified or third-party ebuilds into the package management. However, if you have more than one Gentoo box, you will likely want to keep your private overlay in sync between them.

Note: This Tip uses a centralized approach where changes to the overlays are only made on one machine and then propagated to the rest. If you want decentralized synchronization you could build some scripts with unison (supports 2-way-merges) or rsync and put them here.

Note: This Tip hacks into the layman configuration file for adding a custom, privately owned overlay. If you sync portage using HOWTO Local Rsync Mirror and want to keep (layman) overlay packages synchronized with the rest of your network, then add the /usr/portage/local/layman folder on the server to the rsyncd.conf file and use rsync manually. (See HOWTO Local Rsync Mirror concerning the rsyncd.conf file.) (If you use eix, you should run eix-update afterwords to update the eix search database.) As of layman-1.2, it is said the /usr/local/portage/layman is the new folder location.

The PRO to hacking the layman configuration file (per this wiki), you can use update-eix-layman & update-eix-remote.

The CON to hacking the layman configuration file (per this wiki), for each additional overlay you add to the host (ie. "sunrise"), you also need to go to each client and add each overlay manually. IMO, if I'm doing HOWTO Local Rsync Mirror, it's much easier to just add one entry to the rsyncd.conf & run rsync instead of layman -S on the clients after syncing Portage.


Considering the existence of more than one Gentoo box at your site you should already have set up a local rsync mirror except you're running a fully fledged rsync mirror or have your /usr/portage exported by NFS (in the latter case you should really consider accessing your overlay(s) through NFS as well).

Add one or more modules adjusted for your overlay(s) to your /etc/rsyncd.conf on your mirror machine:

File: /etc/rsyncd.conf
path = /usr/local/portage
comment = My very own private overlay
exclude = /cross-*

Shell: Restart the rsync daemon
/etc/init.d/rsyncd restart


Layman is a very useful python script for retrieving and managing Gentoo overlays on your system.

Shell: Install layman
emerge -av layman

Create a list of your custom portage overlays. If you will be syncing more than one other system, it might be more convenient to upload this to a web server.

File: /usr/portage/local/layman/my-list.xml
<?xml version="1.0" ?>
      type = "rsync"
      src  = "rsync://"
      contact = ""
      name = "private-overlay">

    <description>optional custom description</description>


Now edit your layman config file. Scroll down to the overlays section and add your new list file under the default.

File: /etc/layman/layman.cfg
overlays  :

Download and setup the overlay using the value that you set for name= in my-list.xml. In this case it is private-overlay. Lastly, make a small addition to make.conf so portage can find the new overlay directory.

Shell: Sync up and Modify make.conf
layman -a private-overlay
echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

If you want to re-sync your custom overlay after you have made changes on your rsync server, run this command

Shell: Sync
layman -S


Retrieved from ""

Last modified: Sat, 11 Oct 2008 01:20:00 +0000 Hits: 7,206