Difference between pages "Package:Whenjobs" and "Repository Configuration"

(Difference between pages)
 
(Undo revision 9202 by Duncan.britton (talk))
 
Line 1: Line 1:
{{Ebuild
+
{{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.}}
|Summary=A cron daemon replacement that is powerful, yet simple.
+
|CatPkg=sys-process/whenjobs
+
|Maintainer=Golodhrim,
+
|Repository=Funtoo Overlay
+
}}
+
{{fancywarning|This document is a work in progress, as we are still investigating whenjobs for funtoo usage. For information about it see Funtoo tickets about [http://bugs.funtoo.org/browse/FL-316 whenjobs], [http://bugs.funtoo.org/browse/FL-337 initscript], [http://bugs.funtoo.org/browse/FL-338 User Feedback] and [http://bugs.funtoo.org/browse/FL-351 this document].}}
+
== What are whenjobs? ==
+
  
Whenjobs was written by Richard Jones from [http://www.redhat.com RedHat Linux]. Whenjobs is designed to be a cron daemon replacement with some improvements over normal cron-jobs. Further, we have added some improvements to Whenjobs. Whenjobs gives users a more simple syntax for jobs to run and, with Funtoo improvements, an effective user-management option for whenjobs -- that way we fixed the default behaviour of whenjobs to not been able to run as root and let us execute the daemon on a per-user basis by default.
+
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.
  
=== Questions for help and testing ===
+
== 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.
  
We would like to get your feedback to [http://bugs.funtoo.org/browse/FL-338 FL-338]. So, please test and report your experience with whenjobs.
+
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.
  
== How to install whenjobs ==
+
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.
  
The installation of {{Package|sys-process/whenjobs}} is really easy, just merge it:
+
== Portage configuration ==
 +
=== New repository layout ===
 +
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.
  
<console>
+
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.
###i## emerge -avt whenjobs
+
</console>
+
  
== How to get started ==
+
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:
  
As mentioned above, we added a user-management feature. Also, whenjobs has a changed syntax compared to normal cronjobs -- we will discuss that now.
+
{{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
 +
}}
  
=== User management ===
+
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.
  
The user management for whenjobs is done with a single file located at <tt>/etc/whenjobs.users.conf</tt>. Just add a user to that file by a comma seperated list like:
+
Additionally a <code>[DEFAULT]</code> section may be specified. Options in this section are used as defaults for all repositories.
  
<pre>
+
=== Migrating existing configurations ===
root,user1,user2,user3
+
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:
</pre>
+
 +
{{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.
  
where user1-user3 must be system-usernames, as they are checked. Please do not add any other lines to that file, as there is no way for comments in the file. In addition, adding other lines will break whenjobs -- you will not be able to start the daemon later. Currently, there is no initscript, but we are working on one and that initscript will then use that file in the same way.
+
{{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"
  
=== whenjobs commands ===
+
SYNC="git://github.com/funtoo/ports-2015.git"
 +
SYNC_USER="oleg"
 +
SYNC_UMASK="022"
 +
}}
  
There are some basic commands for whenjobs you should be aware of before we get to explain the script syntax for whenjobs:
+
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
 +
[DEFAULT]
 +
sync-user = oleg
 +
sync-umask = 022
  
To edit/list a job script, use:
+
[funtoo]
 +
location = /var/db/repos/funtoo
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
  
<console>
+
[foo]
# ##i##whenjobs -e | --edit
+
location = /var/db/repos/foo
# ##i##whenjobs -l | --list
+
priority = 1
</console>
+
  
in the above case we added both the short and long version in one line so please use either the '''-e''' or the '''--edit''' version as there is no piping done at that part. We will use the same syntax for further examples if there are multiple ways of calling the function we need.
+
[bar]
 +
location = /var/db/repos/bar
 +
priority = 2
 +
}}
  
Another import part is to set or get variables we want to set or set in whenjobs, that can be done with:
+
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.
  
<console>
+
let's see a real example of tree and overlays added.
to get a variable:
+
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
###i## whenjobs --get variable
+
to set a variable or multiple varibles:
+
###i## whenjobs --set variable=value [variable=value ...]
+
and to display all set variables:
+
###i## whenjobs --variables
+
</console>
+
  
Another important function in whenjobs is the way to start, stop and request the status of the per-user daemon:
+
[gentoo]
<console>
+
location = /usr/portage
# ##i##whenjobs --daemon-start
+
sync-type = git
# ##i##whenjobs --daemon-stop
+
sync-uri = git://github.com/funtoo/ports-2012.git
# ##i##whenjobs --daemon-status
+
# ##i##whenjobs --daemon-restart
+
[funtoo-overlay]
</console>
+
location = /root/git/funtoo-overlay
 
+
Finally we have the ability to inspect running jobs:
+
[funtoo-gnome]
<console>
+
location = /root/git/funtoo-gnome-overlay
# ##i##whenjobs --jobs
+
}}
# ##i##whenjobs --cancel serial
+
funtoo-overlay and funtoo-gnome-overlay are an overlays added on top of regular portage tree.
# ##i##whenjobs --start "name"
+
[[Category:Portage]]
# ##i##whenjobs --tail serial
+
</console>
+
 
+
=== How to get started with whenjobs now ===
+
 
+
First edit the above mentioned <tt>whenjobs.users.conf</tt> file if not already done and start a daemon on a per-user basis with
+
 
+
<console>
+
# ##i##whenjobs --daemon-start
+
</console>
+
 
+
Thats all for starting whenjobs and now we have time to write some whenjobs-scripts. We will use here some basic examples nothing for real time usage but it should be able to give you the impression on how to write your own scripts and use the variables in the later process. First we need to edit our whenjobs-script. This can be done by two ways:
+
 
+
<console>
+
Version A) (manual way, not recommended)
+
# ##i##EDITOR ~/.whenjobs/jobs.ml
+
Edit the file with the scripts you want to use and save it, but after that you need to upload it so that whenjobs knows about it
+
# ##i##whenjobs --upload
+
Version B) (automatically by whenjobs, recommended)
+
# ##i##whenjobs -e  | --edit
+
just save your script now and whenjobs will upload it automatically for you.
+
</console>
+
 
+
So far we are now fine with getting to the scripts, next let us add some basics. We will now start with a periodic call, like if we would like to check out load everyage every 10 minutes we would do it like this:
+
 
+
{{fancywarning|A note aside, the scripts are real shell scripts, so parts beginning with a '''#''' are comments and parts without are the shell script commands that are executed!}}
+
 
+
<source lang="ocaml">
+
every 10 minutes :
+
<<
+
  # Get the current load average.
+
  load=`awk '{print $1}' /proc/loadavg`
+
  whenjobs --set --type float load=$load
+
>>
+
</source>
+
 
+
The power of whenjobs comes in game when you would like to base on a variable you set somewhere else:
+
 
+
<source lang="ocaml">
+
when load >= 6 :
+
<<
+
  mail -s "ALERT: high load average: $load" MAILADDRESS < /dev/null
+
>>
+
</source>
+
 
+
That part will notify a user via email when his load average is greater or equal to 6, as when statements are "edge-triggered".
+
 
+
The '''--type''' switch above for setting a variable can be one of '''bool, int, float, string or unit'''
+
 
+
==== Periodic expressions ====
+
 
+
For periodic expressions you have to use the following syntax
+
 
+
<source lang="ocaml">
+
every <period> :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
where '''<period>''' is one of the following period expressions:
+
 
+
{| class="wikitable"
+
! <period>
+
! Description
+
!
+
! Special <period>
+
! Description
+
|-
+
| second
+
| runs every second
+
|
+
| X seconds
+
| runs every X seconds
+
|-
+
| minute
+
| runs every minute
+
|
+
| X minutes
+
| runs every X minutes
+
|-
+
| hour
+
| runs every hour
+
|
+
| X hours
+
| runs every X hours
+
|-
+
| day
+
| runs every day, at midnight UTC
+
|
+
| X days
+
| runs every X days, at midnight UTC
+
|-
+
| week
+
| runs every week, on a Thursday at midnight UTC
+
|
+
| X weeks
+
| runs every X weeks, on a Thursday at midnight UTC
+
|-
+
| month
+
| runs every month, on the 1st at midnight UTC
+
|
+
| X months
+
| runs every X month, on the 1st at midnight UTC
+
|-
+
| year
+
| runs every year, on the 1/1 at midnight UTC
+
|
+
| X years
+
| runs every X years, on the 1/1 at midnight UTC
+
|-
+
| decade
+
| runs every 10 years
+
|
+
| X decades
+
| runs every X decades
+
|-
+
| century
+
| runs every 100 years
+
|
+
| X centuries
+
| runs every X centuries
+
|-
+
| millenium
+
| runs every 1000 years
+
|
+
| X millenia
+
| runs every X mellenia
+
|}
+
 
+
==== When expressions ====
+
 
+
For dependent jobs you need to use the when-statements with the following syntax:
+
 
+
<source lang="ocaml">
+
when <expr> :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
where '''<expr>''' is a when expression. But don't forget the colon between periods expression or when expression and the shell script.
+
 
+
All in all you can say, that a when-expression is a job which runs, when the described conditions become true.
+
 
+
{| class="wikitable"
+
! <expr>
+
! meaning
+
!
+
! <expr>
+
! meaning
+
|-
+
| expr && expr
+
| boolean "and" of the two sub-expressions
+
|
+
| ! expr
+
| boolean negative of expr
+
|-
+
| expr <nowiki>||</nowiki> expr
+
| boolean "or" of the two sub-expressions
+
|
+
| expr + expr
+
| for numeric sub-expression, this performs addition, for strings it performs string concatenation, else it returns an error.
+
|-
+
| expr < expr
+
| evaluates sub-expressions and compares them with the operator
+
|
+
| expr - expr
+
| evaluates sub-expressions and if both are numeric uses operator on them else returns error
+
|-
+
| expr <= expr
+
| evaluates sub-expressions and compares them with the operator
+
|
+
| expr * expr
+
| evaluates sub-expressions and if both are numeric uses operator on them else returns error
+
|-
+
| expr == expr
+
| evaluates sub-expressions and compares them with the operator
+
|
+
| expr / expr
+
| evaluates sub-expressions and if both are numeric uses operator on them else returns error
+
|-
+
| expr >= expr
+
| evaluates sub-expressions and compares them with the operator
+
|
+
| expr mod expr
+
| evaluates sub-expressions and if both are numeric uses operator on them else returns error (infix operator)
+
|-
+
| expr > expr
+
| evaluates sub-expressions and compares them with the operator
+
|
+
| len expr
+
| returns the length of the string in expr
+
|-
+
| variable
+
| returns the value of named variable
+
|
+
| prev variable
+
| returns previous value of named variable
+
|-
+
| changes variable
+
| same as !(prev variabel == variable)
+
|
+
| increases variable
+
| same as prev variable < variable
+
|-
+
| decreases variable
+
| prev variable > variable
+
|
+
| reloaded ()
+
| do not use it, it does not what you want (manpage warning)
+
|-
+
| false
+
| constant equals always false
+
|
+
| true
+
| constant equals always true
+
|-
+
| "any string"
+
| empty string in boolean = false, else equals true
+
|
+
| N
+
| any integer, boolean 0=false, non-zero=true
+
|-
+
| N. | .N | N.N | N.NeN
+
| and floating point number, boolean 0=false, non-zero=true
+
|
+
|
+
|
+
|}
+
 
+
==== shell scripts ====
+
 
+
The code between '''<< ... >>''' is a simple shell script and is executed using $SHELL. If $SHELL is not set, it is executed with '''/bin/sh'''
+
 
+
{| class="wikitable"
+
! available variable
+
! Description
+
|-
+
| $JOBNAME
+
| The name of the job. If the job has been named explicitly, then that name is available through this variable, else it will be some implicit name like '''job$1'''.
+
|-
+
| $JOBSERIAL
+
| The serial number of the job. This is simply a variable that increments each time a job is run, and is unique to that run of the job.
+
|-
+
| $HOME, $LOGNAME etc
+
| these are available as normal
+
|}
+
 
+
The shell scripts run with its current directory set to an temporary directory, that is cleaned up automacically after the job exists. So you don't have to worry about cleaning them up later. If you would like to store some values permanently, save the files to a well-known directory, eg. $HOME, '''/var''' etc.
+
 
+
All shell scripts are executed as the ordinary user. They have no special privileges.
+
 
+
==== Job names ====
+
 
+
If you like to give a job a unique name use the following syntax:
+
 
+
<source lang="ocaml">
+
job "JOBNAME"
+
every <period> :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
==== OCAML expressions ====
+
 
+
You can also use OCAML expressions in the code. they are useful for factoring common code or strings, for example:
+
 
+
<source lang="ocaml">
+
let prefix = "daily_"
+
 
+
job (prefix ^ "virus_scan")
+
every day :
+
<<
+
  # shell script
+
>>
+
 
+
job (prefix ^ "disk_check")
+
every day :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
===== initial value of variables =====
+
 
+
Variables are empty until they first get set, you can set a default starting value for a variable if you like with the following code
+
 
+
<source lang="ocaml">
+
let () =
+
  Whentools.set_variable "variable" "value";
+
  Whentools.set_variable_int "counter" 0
+
</source>
+
 
+
===== Pre functions =====
+
 
+
You can let arrange to run a '''pre''' function before a job runs. This function may decide to not run the job. One possible usage for that is the that you only want to have one job at time from the same job to run:
+
 
+
<source lang="ocaml">
+
job "only one"
+
pre (Whentools.one ())
+
every <period> :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
===== Post functions =====
+
 
+
The same is for stuff after a job has run. This is handled by the '''post''' function.
+
 
+
<source lang="ocaml">
+
job "talk to me after finished"
+
post (Whentools.mailto "you@example.com")
+
every <period> :
+
<<
+
  # shell script
+
>>
+
</source>
+
 
+
===== Basic available Whentools functions =====
+
 
+
{| class="wikitable"
+
! function
+
! Description
+
|-
+
| style="vertical-align:top;"| whentools.mailto [~only_on_failure:true] [~from:from_address] email_address result
+
| This built-in post function sends the result of the script by email to the given email address.
+
 
+
If the optional "~only_on_failure:true" flag is set, then it is only sent out if the script failed.
+
 
+
If the optional "~from" flag is set, then the from address is set accordingly.  This is sometimes needed when sending mail.
+
 
+
Note the "result" parameter is passed implicitly by the daemon. You do not need to add it.
+
 
+
Here are some examples of using the mailto function:
+
 
+
<source lang="ocaml">
+
job "ex.1"
+
post (Whentools.mailto "you@example.com")
+
every 10 seconds :
+
<<
+
  # shell script 1
+
>>
+
 
+
job "ex.2"
+
post (Whentools.mailto ~only_on_failure:true "you@example.com")
+
every 10 seconds :
+
<<
+
  # shell script 2
+
>>
+
 
+
let from = "me@example.com"
+
let to_addr = "you@example.com"
+
 
+
job "ex.3"
+
post (Whentools.mailto ~from to_addr)
+
every 10 seconds :
+
<<
+
  # shell script 3
+
>>
+
</source>
+
|-
+
| style="vertical-align:top;"| Whentools.max n
+
| This built-in pre function ensures that a maximum of n instances of the job are running.
+
 
+
It checks the list of running jobs, and if n or more instances are already running, then it returns "false", which ensures that the new job is not started.
+
|-
+
| style="vertical-align:top;"| Whentools.one ()
+
| This built-in pre function ensures that only one instance of the job is running.  It is the same as calling: Whentools.max 1
+
 
+
|-
+
| style="vertical-align:top;"| Whentools.set_variable name string
+
| Set variable name to the string
+
|-
+
| Whentools.set_variable_bool name b
+
| Set variable name to the boolean value b
+
|-
+
| style="vertical-align:top;"| Whentools.set_variable_int name i
+
| Set variable name to the integer value i
+
|-
+
| style="vertical-align:top;"| Whentools.set_variable_string name s
+
| Set variable name to the string value <s>.  This is the same as Whentools.set_variable
+
|-
+
| style="vertical-align:top;"| Whentools.set_variable_float name f
+
| Set variable name to the floating point value f
+
|}
+
 
+
For the preinfo passed to the pre functions and results for the post functions have a view in the manpage.
+
 
+
== Examples ==
+
 
+
Finally here are some examples to which questions came up, hope you find them helpful for your first own tries... :)
+
 
+
<source lang="ocaml">
+
every 1 minute :
+
<<
+
  testtime=`date +%H%M`
+
  whenjobs --set --type int test=${testtime}
+
  whenjobs --set --type int runtime=0016
+
>>
+
 
+
when test == 0017 :
+
<<
+
  echo `date` >\> ~/test.log
+
>>
+
 
+
when test == runtime
+
<<
+
  whenjobs --get runtime >\> ~/test.log
+
>>
+
</source>
+
 
+
The above whenjobs have the need to run each day at a specific time, so we show you here two ways of doing it.
+
 
+
First we define a variable test for whenjobs based on the date with the HHMM output what would for example result in 0017 for 12:17am and 1428 for 2:28pm. then in the first when expression we test if our variable equals 0017 and if yes it runs, the second version is to define a second variable called runtime and then do like the second test does a test for it based on comparing both variables.
+
 
+
But now enough with that long doc, happy whenjobing for all of you... :)
+
 
+
 
+
[[Category:HOWTO]]
+
[[Category:Labs]]
+
[[Category:Ebuilds]]
+
{{EbuildFooter}}
+

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.