Difference between pages "Dell PowerEdge 11G Servers" and "Repository Configuration"

(Difference between pages)
 
(Undo revision 9202 by Duncan.britton (talk))
 
Line 1: Line 1:
__NOTITLE__
+
{{Warning|This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.}}
  
== Funtoo Linux on Dell PowerEdge 11G Servers ==
+
Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.
  
This section provides valuable information regarding the use of Funtoo Linux on Dell PowerEdge 11G servers. This information has been validated on Dell PowerEdge R710 systems with Intel Xeon 5500 processors but should also apply to varying degrees to the entire Dell PowerEdge 11G family.
+
== Multiple repository layout ==
 +
One of the most important changes is the switch from the old ''overlay'' layout to a new cleaner ''repository'' system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.
  
'''Please be sure to read all important compatibility notes associated with your specific Dell PowerEdge model, which can be found in the ''Important Compatibility Notes'' column in the table below:'''
+
The old layout was based on the concept of one ''main tree'' and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.
  
{| {{table}}
+
The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called ''funtoo'' (a drop-in replacement for Gentoo's ''gentoo'' repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.
!System
+
!Form Factor
+
!Processor
+
!Integrated NIC
+
!Important Compatibility Notes
+
|-
+
|R210
+
|1U
+
|Intel Xeon 3400 series
+
|BCM 5716
+
|<ref group="hw" name="bcm">'''When using a non-RHEL-5 kernel, it's highly recommended to <tt>emerge broadcom-netxtreme2</tt> after installing your kernel, in order to use the latest drivers from Broadcom.com rather than the in-kernel <tt>bnx2</tt> (1GbE) or <tt>bnx2x</tt> (10GbE) drivers. This will help resolve firmware initialization and other hardware compatibility issues that may result in your network interfaces being unavailable at boot or performing sub-optimally under load. See [[#Kernel Compatibility|Kernel Compatibility]] for more information.'''</ref>
+
|-
+
|R310
+
|1U
+
|Intel Xeon 3400 series
+
|2x1GbE (BCM 5716)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R410
+
|1U
+
|Intel Xeon 5500 series
+
|2x1GbE (BCM 5716)
+
|<ref group="hw" name="bcm"/><ref group="hw" name="intel5500">'''The Intel Xeon 5500 and 5600 series processors used in Dell PowerEdge 11G servers have known errata (bugs) related to C-states (CPU power saving states) that can and will result in unexpected and unpleasant server behavior in real-world, day-to-day operation. Intel has released CPU microcode updates in 2010 and early 2011 to address these issues. Be sure to update your BIOS to the most recent available from Dell. Dell includes Intel CPU microcode updates as part of their BIOS updates. BIOS 3.0.0 or greater is recommended.'''
+
  
For more information on Intel Xeon 5500 errata, see [http://www.intel.com/assets/pdf/specupdate/321324.pdf Intel's Xeon Processor 5500 Series Specification Update, April 2011].</ref>
+
== Portage configuration ==
|-
+
=== New repository layout ===
|R415
+
The repository configuration should be stored in <code>/etc/portage/repos.conf</code>. It can be either a single file or a directory containing one or more ''.conf'' files.
|1U
+
|AMD Opteron 4100 series
+
|2x1GbE (BCM 5716)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R510
+
|2U
+
|Intel Xeon 5500 series
+
|2x1GbE (BCM 5716)
+
|<ref group="hw" name="bcm"/><ref group="hw" name="intel5500"/>
+
|-
+
|R515
+
|2U
+
|AMD Opteron 4100 series
+
|2x1GbE (BCM 5716)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R710
+
|2U
+
|Intel Xeon 5500/5600 series
+
|4x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/><ref group="hw" name="intel5500"/>
+
|-
+
|R715
+
|2U
+
|AMD Opteron 6100 series
+
|4x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R810
+
|2U
+
|Intel Xeon 6500/7500 series
+
|4x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R815
+
|2U
+
|AMD Opteron 6100 series
+
|4x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|R910
+
|4U
+
|Intel Xeon 7500/E7 series
+
|4x1GbE (BCM 5709c) or 2x10GbE + 2x1GbE (BCM 57771)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|T310
+
|Tower
+
|Intel Xeon 3400 series
+
|optional BCM 5709c (PCI-E)
+
|<ref group="hw" name="bcm"/>
+
|-
+
|T610
+
|Tower
+
|Intel Xeon 5500/5600 series
+
|2x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/><ref group="hw" name="intel5500"/>
+
|-
+
|T710
+
|Tower
+
|Intel Xeon 5500/5600 series
+
|4x1GbE (BCM 5709c)
+
|<ref group="hw" name="bcm"/><ref group="hw" name="intel5500"/>
+
|-
+
|}
+
  
==== Important Hardware Notices ====
+
The default configuration is installed as <code>/usr/share/portage/config/repos.conf</code>. This file is internal configuration file installed with portage ebuild and should '''not''' be modified. Instead, the configuration in <code>/etc/portage/repos.conf</code> can override the defaults specified there.
  
<references group="hw"/>
+
The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:
  
=== Updating Firmware ===
+
{{file|name=/etc/portage/repos.conf/funtoo.conf|desc=Example configuration override for Funtoo repository to move it to non-standard location|body=
 +
[funtoo]
 +
# moved to non-standard location!
 +
location = /var/db/repos/funtoo
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
 +
auto-sync = yes
 +
}}
  
The most reliable method to update firmware is to use Dell Repository Manager. This program requires Windows but has the ability to make a bootable Linux ISO image that can update your server firmware in an efficient manner. The PowerEdge R710 also has a built-in "Unified Server Configurator" that can be used to update firmware in a pinch, but it is can take an extremely long time to download and apply server updates.
+
The most useful repository configuration options are listed below:
 +
;location: ''Obligatory.'' Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next ''emerge --sync''. Otherwise, the directory must exist.
 +
;priority: Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
 +
;auto-sync: Specifies whether ''emerge --sync'' should update the repository. Defaults to ''yes'' if ''sync-type'' is specified, ''no'' otherwise.
 +
;sync-depth: Specifies ''--depth'' for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass ''--depth'' at all).
 +
;sync-type: Specifies syncing/update method. Can be one of: ''cvs'', ''git'', ''rsync'', ''svn''.
 +
;sync-umask: Specifies the umask used when updating/syncing the repository.
 +
;sync-uri: Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
 +
;sync-user: Specifies the user[:group] used to update/sync the repository. If ''FEATURES=usersync'' is used, defaults to the credentials of directory owner.
  
'''Use of the Dell Repository Manager to build a Linux bootable ISO image is the recommended method of updating Dell firmware. A step-by-step guide for using Dell Repository Manager can be found below:'''
+
Additionally a <code>[DEFAULT]</code> section may be specified. Options in this section are used as defaults for all repositories.
  
==== Dell Repository Manager ====
+
=== Migrating existing configurations ===
'''Important: It is recommended that you download the latest Dell Repository Manager which can be downloaded following instructions in [http://en.community.dell.com/support-forums/servers/f/177/p/19433362/20058722.aspx#20058722 this thread post]. It resolves issues creating ISOs under Windows 7.'''
+
The new configuration format provides replacement for existing configuration done through <code>/etc/portage/make.conf</code> and environment variables. While the variables are still supported for backwards compatibility, users are recommended to move to the new configuration scheme. Funtoo portage ebuild is planned to  make the migration unattended (repos.conf installed automatically to ease the config steps) with the following file:
 +
 +
{{file|name=/etc/portage/repos.conf/funtoo.conf|body=
 +
[funtoo]
 +
location = /usr/portage
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
 +
auto-sync = yes
 +
}}
 +
The following replacements are provided for existing variables:
 +
;PORTDIR: Used to specify main tree location. Replaced by ''location'' key in the section corresponding to the default repository (<code>[funtoo]</code> by default).
 +
;PORTDIR_OVERLAY: Used to specify locations of overlays. Each of the paths needs to be replaced with a separate repository section, with the path placed in ''location'' key. Additionally, ''priority'' may be used to force specific ordering of ebuild overrides.
 +
;SYNC: Used to specify URI for syncing the main repository, also implied a protocol for doing that. Replaced by the ''sync-uri'' and ''sync-type'' keys in the default repository section.
 +
;SYNC_UMASK: Used to specify umask for syncing repositories. Replaced by ''sync-umask'' key in repository configuration. Can be specified in <code>[DEFAULT]</code> section to apply to all repositories.
 +
;SYNC_USER: Used to specify user credentials for syncing repositories. Replaced by ''sync-user'' key in repository configuration. Can be specified in <code>[DEFAULT]</code> section to apply to all repositories.
  
Here's a complete list of steps to update Dell firmware using the Dell Repository Manager:
+
{{file|name=/etc/portage/make.conf|desc=Example old make.conf file|body=
 +
# user changed PORTDIR location
 +
PORTDIR="/var/db/repos/funtoo"
 +
PORTDIR_OVERLAY="/var/db/repos/foo /var/db/repos/bar"
  
# Download Dell Repository Manager from http://ftp.dell.com/FOLDER00313115M/1/Dell_Repository_Manager_1.4.113.msi and install on a Windows system.
+
SYNC="git://github.com/funtoo/ports-2015.git"
# Launch the program.
+
SYNC_USER="oleg"
# In the main window, choose to automatically import ftp.dell.com, and click "Import Repository": <br/>[[image:dellrepoman.PNG]]
+
SYNC_UMASK="022"
# Welcome: The Create/Load Repository dialog will open. Select "Create New Repository" and click "Next".
+
}}
# Name and Description: Type in a name of your choice, such as "Dell R710", and click "Next".
+
# Select Repository: Select "(Server) ftp.dell.com" and click "Next".
+
# Select Form Factor: Select the type(s) of equipment you want to build a driver disk for and click "Next".
+
# Select OS: Select "Linux". Click "Next".
+
# Select Models: Choose the specific model of equipment ("PowerEdge R710", for example.) Click "Next".
+
# Select Bundle(s): Choose to "ONLY include most recent and custom bundle(s)". Click "Next".
+
# Additional Components: Select "Yes". Click "Next".
+
# Summary: click "Finish".
+
# "Please wait" will appear for a few minutes, and then the dialog will disappear.
+
# The "Bundles" tab will now be active with your bundle visible.
+
# Select your bundle by clicking the square check-box to the left of it.
+
# Click "Export" in the lower right corner of the main window, and click "Next" on the Welcome screen.
+
# Export Destination: Select "Deployment Media (Linux only) Export to ISO/Script format for deployment." Click "Next".
+
# At this point, you may be prompted to install a plugin. Install the plugin and click "Next".
+
# Select an output folder for the ISO, click "OK", and then "Next".
+
# Select Custom Script: Select "No" and click "Next".
+
# Click "Finish".
+
# Your ISO will take 5-10 minutes to build. The program will let you know when it's done.
+
# Burn ISO to CD-R/DVD-R.
+
# Insert burnt disc into server, reboot server, press F11 for boot menu and choose to boot from CD.
+
# The disc will boot. Select the first menu option to launch the firmware update process.
+
# The process will take 20-30 minutes to complete. Press Alt-F2 for a console if you get bored.
+
# When the firmware update process is complete, a message will appear on the screen. Hit Enter to reboot.
+
  
The disc can now be used to update other similar systems in your datacenter.
+
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
 +
[DEFAULT]
 +
sync-user = oleg
 +
sync-umask = 022
  
==== iDRAC6 ====
+
[funtoo]
 +
location = /var/db/repos/funtoo
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
  
iDRAC is the Dell Integrated Remote Access Controller, which is typically accessed via the dedicated management interface using a Web browswer.
+
[foo]
 +
location = /var/db/repos/foo
 +
priority = 1
  
Sometimes, the iDRAC firmware will not be successfully updated via the firmware CD-R created using the steps in the section above. This was experienced on our servers when attempting to update from iDRAC firmware 1.54 to 1.70. To work around this issue, you can log in directly to the iDRAC via a Web browser and update the iDRAC's firmware (just the iDRAC firmware itself, not the firmware of other system components) via its user interface.
+
[bar]
 +
location = /var/db/repos/bar
 +
priority = 2
 +
}}
  
To do this, follow these steps:
+
The <code>repos.conf</code> configuration can be further extended with ''sync-type'' and ''sync-uri'' for overlays to get ''emerge --sync'' updating them automatically.
  
# Go to http://support.dell.com, and download the latest Dell iDRAC6 firmware. You will want to download the Windows executable format file, ie. <tt>iDRAC6_1.70_A02_FW_IMG.exe</tt>.
+
let's see a real example of tree and overlays added.  
# Execute this file on a Windows machine. It is a self-extracting archive and will prompt you for a location to store the firmware. Choose a location and a file named <tt>firmimg.d6</tt> will be extracted. This is the iDRAC firmware you will upload.
+
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
# Log in to the iDRAC using a Web browser. If updating from 1.54, use Google Chrome instead of Internet Explorer 9 to avoid issues.
+
# Select "Remote Access" (or in newer versions, "iDRAC Settings") from the menu on the left, and the "Update" tab at the top of the page.
+
# On this page, click the "Choose File" button and select the <tt>firmimg.d6</tt> file extracted earlier.
+
# Click "Upload". Uploading the firmware will take a minute or two.
+
# Once the firmware image is uploaded, you will be able to click a button to update the firmware. You will be presented with a status page similar to this:<br/>[[Image:Idrac6update.PNG]]
+
# Once the iDRAC firmware is 100% complete, you can reload the iDRAC Web page and log in to the new version of iDRAC.
+
# Note that because iDRAC is independent from the underlying hardware, your Linux system will typically not power cycle during this process, so it will still be available.
+
  
=== Kernel Compatibility ===
+
[gentoo]
 
+
location = /usr/portage
The following table documents kernel compatibility with the Dell PowerEdge R710 server, and is likely to apply to other PowerEdge 11G servers based on Intel Xeon 5500/5600 series processors.
+
sync-type = git
 
+
sync-uri = git://github.com/funtoo/ports-2012.git
{{fancynote|Funtoo Linux kernel testing is performed on Dell PowerEdge R710 servers equipped with Intel 5500 series processors.}}
+
 
+
[funtoo-overlay]
All kernels listed below were built by setting the <tt>binary</tt> USE variable and emerging, which causes full kernel sources as well as a binary kernel and initrd (built using <tt>genkernel</tt>) to be installed. Note that for the <tt>openvz-rhel5-stable</tt> kernel, udev must be downgraded to 146-r3 in order for the system to function properly after reboot. This can be accomplished by adding <tt>>=sys-fs/udev-147</tt> to <tt>/etc/portage/package.mask</tt> and running <tt>emerge udev</tt> prior to booting your new kernel.
+
location = /root/git/funtoo-overlay
 
+
{| {{table}}
+
[funtoo-gnome]
!Kernel
+
location = /root/git/funtoo-gnome-overlay
!Version
+
}}
!Minimum Dell BIOS
+
funtoo-overlay and funtoo-gnome-overlay are an overlays added on top of regular portage tree.
!Req'd USE flags
+
[[Category:Portage]]
!Stability
+
!Req'd drivers
+
!Req'd udev
+
|-
+
|openvz-rhel5-stable
+
|2.6.18.028.089.1
+
|3.0.0<ref group="kernel" name="bios">Without an up-to-date BIOS, you may experience system instability or a system clock that jumps forward (and back) 5 minutes for no apparent reason. Upgrading to at least Dell BIOS 3.0.0 should update Intel CPU microcode sufficiently to correct these issues.</ref>
+
|<tt>binary</tt>
+
|'''Excellent'''
+
|Broadcom <tt>bnx2</tt> driver module bundled with kernel appears to be OK
+
|=sys-fs/udev-146*
+
|-
+
|openvz-rhel5-stable
+
|2.6.18.028.091.1
+
|3.0.0<ref group="kernel" name="bios"/>
+
|<tt>binary</tt>
+
|'''Excellent'''
+
|Broadcom <tt>bnx2</tt> driver module bundled with kernel appears to be OK
+
|=sys-fs/udev-146*
+
|-
+
|ubuntu-server
+
|2.6.32.32.62
+
|3.0.0<ref group="kernel" name="bios"/>
+
|<tt>binary</tt>
+
|'''Excellent'''
+
|<tt>emerge broadcom-netxtreme2</tt> for reliable BCM5709+ support (integrated NIC)
+
|N/A <ref group="kernel" name="udevany"/>
+
|-
+
|openvz-rhel6-stable
+
|2.6.32.014.1
+
|3.0.0<ref group="kernel" name="bios"/>
+
|<tt>binary</tt>
+
|''Buggy, do not use''
+
|<tt>emerge broadcom-netxtreme2</tt> for reliable BCM5709+ support (integrated NIC)
+
|N/A <ref group="kernel" name="udevany">Any standard Funtoo Linux udev version is fine.</ref>
+
|-
+
|openvz-rhel6-stable
+
|2.6.32.015.1
+
|3.0.0<ref group="kernel" name="bios"/>
+
|<tt>binary</tt>
+
|''Buggy, do not use''
+
|<tt>emerge broadcom-netxtreme2</tt> for reliable BCM5709+ support (integrated NIC)
+
|N/A <ref group="kernel"  name="udevany"/>
+
|-
+
|openvz-rhel6-stable
+
|2.6.32.016.1
+
|3.0.0<ref group="kernel" name="bios"/>
+
|<tt>binary</tt>
+
|''Buggy, do not use''
+
|<tt>emerge broadcom-netxtreme2</tt> for reliable BCM5709+ support (integrated NIC)
+
|N/A <ref group="kernel" name="udevany"/>
+
|}
+
 
+
<references group="kernel"/>
+
 
+
== Server Best Practices ==
+
 
+
This section contains a list of recommended programs, utilities and best practices for production servers.
+
 
+
=== Accurate System Time (NTP) ===
+
 
+
My favorite and recommended NTP client/server is <tt>net-misc/chrony</tt>. It is recommended for production servers:
+
 
+
<pre>
+
# emerge chrony
+
# rc-update add chronyd default
+
</pre>
+
 
+
Use something like the following for your <tt>/etc/chrony/chrony.conf</tt>:
+
 
+
<pre>
+
server time.apple.com
+
maxupdateskew 100
+
driftfile /etc/chrony/chrony.drift
+
keyfile /etc/chrony/chrony.keys
+
commandkey 1
+
dumponexit
+
dumpdir /var/log/chrony
+
initstepslew 10 time.apple.com
+
logdir /var/log/chrony
+
log measurements statistics tracking
+
logchange 0.5
+
mailonchange me@emailprovider.com 0.5
+
rtcfile /etc/chrony/chrony.rtc
+
rtconutc
+
sched_priority 1
+
lock_all
+
</pre>
+
 
+
Chronyd can then be started immediately by running <tt>rc</tt> to start all new services:
+
 
+
<pre>
+
# rc
+
</pre>
+
 
+
You should notice a marked improvement in your system clock's accuracy. If your system time was off by a significant amount, <tt>chronyd</tt> will gradually correct your clock while the system runs.
+
 
+
=== SMART Disk Monitoring ===
+
 
+
Emerge <tt>smartmontools</tt> and use an <tt>/etc/smartd.conf</tt> with these settings for a PERC 6/i with 5 physical disks installed:
+
 
+
<pre>
+
/dev/sda -m myemail@foo.com -d megaraid,0
+
/dev/sda -m myemail@foo.com -d megaraid,1
+
/dev/sda -m myemail@foo.com -d megaraid,2
+
/dev/sda -m myemail@foo.com -d megaraid,3
+
/dev/sda -m myemail@foo.com -d megaraid,4
+
</pre>
+
 
+
To figure out what configuration to use for your system, use the following command:
+
 
+
<pre>
+
# smartctl -d megaraid,X --all /dev/sdY
+
</pre>
+
 
+
Start using X=0 and Y=a, and keep incrementing X until you discover all physical disks backing sda. Then repeat with sdb, etc. until you discover all physical disks in your system. In typical configurations, you will have <tt>megaraid,0</tt> thru <tt>megaraid,(num_physical_disks-1)</tt>.
+
 
+
{{fancynote|On Dell R910s with PERC H700, all physical disks are addressable through all /dev/sdY simultaneously, so there is no need to iterate through Y. ie: all of the same physical disks will be shown simultaneously for /dev/sda, /dev/sdb, /dev/sdc etc... so there is no need to repeat the steps for sdY+1 and onwards.}}
+
 
+
[[Category:Hardware Compatibility]]
+

Revision as of 04:52, February 27, 2015

Warning

This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.

Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.

Multiple repository layout

One of the most important changes is the switch from the old overlay layout to a new cleaner repository system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.

The old layout was based on the concept of one main tree and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.

The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called funtoo (a drop-in replacement for Gentoo's gentoo repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.

Portage configuration

New repository layout

The repository configuration should be stored in /etc/portage/repos.conf. It can be either a single file or a directory containing one or more .conf files.

The default configuration is installed as /usr/share/portage/config/repos.conf. This file is internal configuration file installed with portage ebuild and should not be modified. Instead, the configuration in /etc/portage/repos.conf can override the defaults specified there.

The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:

/etc/portage/repos.conf/funtoo.conf - Example configuration override for Funtoo repository to move it to non-standard location
[funtoo]
# moved to non-standard location!
location = /var/db/repos/funtoo
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git
auto-sync = yes

The most useful repository configuration options are listed below:

location
Obligatory. Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next emerge --sync. Otherwise, the directory must exist.
priority
Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
auto-sync
Specifies whether emerge --sync should update the repository. Defaults to yes if sync-type is specified, no otherwise.
sync-depth
Specifies --depth for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass --depth at all).
sync-type
Specifies syncing/update method. Can be one of: cvs, git, rsync, svn.
sync-umask
Specifies the umask used when updating/syncing the repository.
sync-uri
Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
sync-user
Specifies the user[:group] used to update/sync the repository. If FEATURES=usersync is used, defaults to the credentials of directory owner.

Additionally a [DEFAULT] section may be specified. Options in this section are used as defaults for all repositories.

Migrating existing configurations

The new configuration format provides replacement for existing configuration done through /etc/portage/make.conf and environment variables. While the variables are still supported for backwards compatibility, users are recommended to move to the new configuration scheme. Funtoo portage ebuild is planned to make the migration unattended (repos.conf installed automatically to ease the config steps) with the following file:

/etc/portage/repos.conf/funtoo.conf
[funtoo]
location = /usr/portage
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git
auto-sync = yes

The following replacements are provided for existing variables:

PORTDIR
Used to specify main tree location. Replaced by location key in the section corresponding to the default repository ([funtoo] by default).
PORTDIR_OVERLAY
Used to specify locations of overlays. Each of the paths needs to be replaced with a separate repository section, with the path placed in location key. Additionally, priority may be used to force specific ordering of ebuild overrides.
SYNC
Used to specify URI for syncing the main repository, also implied a protocol for doing that. Replaced by the sync-uri and sync-type keys in the default repository section.
SYNC_UMASK
Used to specify umask for syncing repositories. Replaced by sync-umask key in repository configuration. Can be specified in [DEFAULT] section to apply to all repositories.
SYNC_USER
Used to specify user credentials for syncing repositories. Replaced by sync-user key in repository configuration. Can be specified in [DEFAULT] section to apply to all repositories.
/etc/portage/make.conf - Example old make.conf file
# user changed PORTDIR location
PORTDIR="/var/db/repos/funtoo"
PORTDIR_OVERLAY="/var/db/repos/foo /var/db/repos/bar"

SYNC="git://github.com/funtoo/ports-2015.git"
SYNC_USER="oleg"
SYNC_UMASK="022"
/etc/portage/repos.conf - Replacement repos.conf file
[DEFAULT]
sync-user = oleg
sync-umask = 022

[funtoo]
location = /var/db/repos/funtoo
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git

[foo]
location = /var/db/repos/foo
priority = 1

[bar]
location = /var/db/repos/bar
priority = 2

The repos.conf configuration can be further extended with sync-type and sync-uri for overlays to get emerge --sync updating them automatically.

let's see a real example of tree and overlays added.

/etc/portage/repos.conf - Replacement repos.conf file
[gentoo]
location = /usr/portage
sync-type = git
sync-uri = git://github.com/funtoo/ports-2012.git
 
[funtoo-overlay]
location = /root/git/funtoo-overlay
 
[funtoo-gnome]
location = /root/git/funtoo-gnome-overlay

funtoo-overlay and funtoo-gnome-overlay are an overlays added on top of regular portage tree.