
<sect2 id="configuration.fileformat"><title>File format</title>
<para>
The file consists of directives, sections and parameters. A section begins
with thename of the section in square brackets and continues until the next
section begins ('ini'-like format). Sections contain parameters of the form:
<screen>
name = value
</screen>
</para><para>
The  file  is line-based - that is, each newline-terminated line represents
either a comment, a section name or a parameter. Any line beginning with a
hash (``#'') character is ignored, as are lines containing only whitespace.
</para><para>

In most string paramameters environment variables are expanded:
<screen>
path = $HOME/foo
</screen>
</para>
</sect2><sect2 id="configuration.directives"><title>Special directives</title>
<para>
File can be combined from multiple configuration files with <option>%include</option>
directive. Either local and remote HTTP/FTP files can be included, examples:
<screen>
%include /etc/foo.conf            # simply include /etc/foo.conf
%include foo.conf                 # include foo.conf from directory of includer
%include http://bar.org/foo.conf  # include foo.conf from remote location
</screen>
</para>
<para>
Any "[global]" sections from included files are simply ignored.
Remote files are cached, they can be updated using <option>--upconf</option>
switch.
</para>

<para>
Second directive, <option>%includedir</option> includes all *.conf files from given directory,
examples:
<screen>
%include repos.d                  # include all *.conf files from repos.d subdirectory
%include /etc/repos.d             # include all *.conf files from /etc/repos.d
</screen>
</para>
</sect2><sect2 id="configuration.macros"><title>Macros</title>
<para>
Simple macros are supported. Macros are declared as paramameter with
underscore ('_') at beginning:
<screen>
_foo = /bar
</screen>
and can be expanded in any following value in %{NAME} form:
<screen>
path = %{_foo}/dir    # path will be '/bar/dir'
</screen>
Macros are local to file beeing declared, they are not visible in
included files as they are not visible to includer.
</para>
</sect2><sect2 id="configuration.sectiondescr"><title>Section descriptions</title>
<para>
There are three section types: [global], [source] and [fetcher].
<variablelist><title></title>
  <varlistentry><term><option>[global]</option></term>
    <listitem><para>
    Section contains global paramameters. May be declared multiple
    times, in this case content of all global sections are concatenated.
    </para></listitem>
  </varlistentry>

  <varlistentry><term><option>[source]</option></term>
    <listitem><para>
    This section contains poldek's repository configuration. Each section
    describes one repository.
    </para></listitem>
  </varlistentry>

  <varlistentry><term><option>[fetcher]</option></term>
    <listitem><para>
    Configuration of external file getters. Each section declares one
    external downloader.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>
<para>
To make things simpler default configuration consists of several files.
Repositories are declared in separate <filename>source.conf</filename>
and <filename>*-source.conf</filename>, file getters are declared in
<filename>fetch.conf</filename>. All of them are included by
<filename>poldek.conf</filename>.
</para>
</sect2><sect2 id="configuration.global">
  <title>Parameters of [global] section</title>
  <variablelist>
    <title/>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.global.default_index_type">default index type</option>
      </term>
      <listitem>
        <para>
    This parameter allows to configure the default repository index type.
    </para>
        <para>
          Default: default index type = pndir</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.cachedir">cachedir</option>
      </term>
      <listitem>
        <para>
     Cache directory for downloaded files. NOTE that parent directory of cachedir
     must exist.
    </para>
        <para>
          Default: cachedir = $HOME/.poldek-cache</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.runas">runas</option>
      </term>
      <listitem>
        <para>
     Switch to ordinary user at startup when executed by root
    </para>
        <para>
          Default: runas = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.use_sudo">use sudo</option>
      </term>
      <listitem>
        <para>
    Permits using root privileges for installation only. If set to "auto" then
    automatically turned on when poldek executed as ordinary user.
    </para>
        <para>
          Default: use sudo = auto</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.load_apt_sources_list">load apt sources list</option>
      </term>
      <listitem>
        <para>
    Load <filename>/etc/apt/sources.list</filename>.
    </para>
        <para>
          Default: load apt sources list = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.vfile_external_compress">vfile external compress</option>
      </term>
      <listitem>
        <para>
    Handle gzipped indexes externally (needed on RedHat 9 and Fedora Core 1 and 2).
    This option is a workaround for broken zlib linked into librpm; with enabled
    'auto zlib in rpm' poldek tries to detect such case and then enables external
     *.gz handling automatically.
    </para>
        <para>
          Default: vfile external compress = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.auto_zlib_in_rpm">auto zlib in rpm</option>
      </term>
      <listitem>
        <para>
    Auto detection of zlib linked into librpm. See 'vfile external compress'
    description.
    </para>
        <para>
          Default: auto zlib in rpm = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.autoupa">autoupa</option>
      </term>
      <listitem>
        <para>
    Automatically download whole index if incremental update fails.
    </para>
        <para>
          Default: autoupa = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.exclude_path">exclude path</option>
      </term>
      <listitem>
        <para>
    Do not save given paths into created indexes. This option may significantly
    reduce index size. Example (notice missing starting '/'):
    <screen>
 exclude path = usr/share/doc:usr/share/man:usr/src
    </screen>
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.pm_command">pm command</option>
      </term>
      <listitem>
        <para>
    Full path name to a PM (rpm for now) binary.
    </para>
        <para>
          Default: pm command = /bin/rpm</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.sudo_command">sudo command</option>
      </term>
      <listitem>
        <para>
    Full path name to sudo binary.
    </para>
        <para>
          Default: sudo command = /usr/bin/sudo</para>
      </listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <title>File downloaders configuration</title>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.global.vfile_ftp_sysuser_as_anon_passwd">vfile ftp sysuser as anon passwd</option>
      </term>
      <listitem>
        <para>
    Send ${USER}@${HOSTNAME} as anonymous FTP password (by default
    <literal>'poldek@znienacka.net'</literal> is sent)
    </para>
        <para>
          Default: vfile ftp sysuser as anon passwd = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.default_fetcher">default fetcher</option>
      </term>
      <listitem>
        <para>
     File getters configuration parameter. By this option URL handlers may be configured.
     To get file from HTTP and FTP servers poldek uses its internal client (what is
     recommended), although it can be changedby this option. Others protocols handled
     by external utilities can be configured also. The syntax is:
     <screen>
 default fetcher = PROTOCOL[,PROTOCOL...]:FETCHER_NAME
     </screen>

     where FETCHER_NAME is a name of one of the fetcher preconfigured in [fetch]
     sections (placed in <filename>fetch.conf</filename> in default configuration).
     Examples:
     <screen>
 default fetcher = ftp,http:internal
 default fetcher = https:wget
 default fetcher = cdrom:vfjuggle
     </screen>
     <filename>vfjuggle</filename> is a cdrom getter supplied with poldek.
    </para>
        <para>
          Default: default fetcher = http,ftp: internal</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.proxy">proxy</option>
      </term>
      <listitem>
        <para>
    Proxies for internal FTP and HTTP client may be configured in usual
    way, by environment variables ftp_proxy and http_proxy, or by this option.
    Its syntax is similar to "default fetcher" one:
    <screen>
 proxy = PROTOCOL[,PROTOCOL...]:PROXY_URL
    </screen>
    Example:
    <screen>
 proxy = http: http://w3cache.foo.org:8080
    </screen>
    </para>
        <para>
          Default: proxy = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.noproxy">noproxy</option>
      </term>
      <listitem>
        <para>
    Comma separated list of hosts or domains which will not be accessed via proxy.
    Option overrides no_proxy environment variable.
    Example:
    <screen>
 noproxy = localhost, .pl, ftp.foo.bar.org
    </screen>
    </para>
        <para>
          Default: noproxy = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.vfile_retries">vfile retries</option>
      </term>
      <listitem>
        <para>
    Internal HTTP and FTP client is stubborn, it retries to retrive
    file if connection breaks. This option tells it how many times
    it should try.
    </para>
        <para>
          Default: vfile retries = 128</para>
      </listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <title>Installation options</title>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.global.particle_install">particle install</option>
      </term>
      <listitem>
        <para>
     Install packages in small groups instead of doing all-or-nothing
     installations.
    </para>
        <para>
          Default: particle install = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.keep_downloads">keep downloads</option>
      </term>
      <listitem>
        <para>
    Do not remove downloaded packages after its successful installation.
    </para>
        <para>
          Default: keep downloads = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.unique_package_names">unique package names</option>
      </term>
      <listitem>
        <para>
    Controls visibility of multiple package instances with different EVR.
    If on, only one, highest version will be visible.
    </para>
        <para>
          Default: unique package names = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.promoteepoch">promoteepoch</option>
      </term>
      <listitem>
        <para>
    Epoch autopromotion during dependency comparision. RPM specific.
    Set it up if you are using system with rpm prior to 4.2.1 version.
    </para>
        <para>
          Default: promoteepoch = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.confirm_installation">confirm installation</option>
      </term>
      <listitem>
        <para>
    Confirm packages installation.
    </para>
        <para>
          Default: confirm installation = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.confirm_removal">confirm removal</option>
      </term>
      <listitem>
        <para>
    Confirm packages removal.
    </para>
        <para>
          Default: confirm removal = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.choose_equivalents_manually">choose equivalents manually</option>
      </term>
      <listitem>
        <para>
    Let the user select package among equivalents.
    </para>
        <para>
          Default: choose equivalents manually = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.hold">hold</option>
      </term>
      <listitem>
        <para>
    Prevent package listed from being upgraded if they are already installed.
    <screen>
 hold = kernel*
    </screen>
    </para>
        <para>
          Default: hold = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.ignore">ignore</option>
      </term>
      <listitem>
        <para>
    Ignore package list - packages fits given mask will be invisible.
    <screen>
 ignore = *-smp-* foo*
 ignore = vserver-packages
    </screen>
    </para>
        <para>
          Default: ignore = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.allow_duplicates">allow duplicates</option>
      </term>
      <listitem>
        <para>
    Conflicts with already installed packages are treated as resolved
    if at least one of multiple-installed package satisfies conflict.
    rpm doesn't support such cases, so <option>--pm-nodeps</option> is needed (use with
    care).
    </para>
        <para>
          Default: allow duplicates = yes</para>
      </listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <title>RPM specific options</title>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.global.rpmdef">rpmdef</option>
      </term>
      <listitem>
        <para>
    rpm macros can be set by this option. Examples:
    <screen>
 rpmdef   = _install_langs pl:pl_PL:lt:lt_LT
    </screen>
    Do not install any documentation:
    <screen>
 rpmdef  = _netsharedpath /usr/share/info:/usr/share/man
 rpmdef  = _excludedocs 1
    </screen>
	If non-zero, all erasures will be automagically repackaged.
    <screen>
 rpmdef  = _repackage_all_erasures 1
    </screen>
    </para>
        <para>
          Default: rpmdef = </para>
      </listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <title>Dependency processing settings</title>
    <para>
 Subtle dependency processing options, they should not be changed
 unless you know what you are doing
</para>
    <varlistentry>
      <term>
        <option id="configuration.global.auto_directory_dependencies">auto directory dependencies</option>
      </term>
      <listitem>
        <para>
    RPM 4.4.6 introduces auto dependencies based on package directories.
    Option controls this feature.
    </para>
        <para>
          Default: auto directory dependencies = auto</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.follow">follow</option>
      </term>
      <listitem>
        <para>
    Automatically install packages required by installed ones.
    </para>
        <para>
          Default: follow = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.greedy">greedy</option>
      </term>
      <listitem>
        <para>
    Greedy upgrades, i.e. upgrade packages which dependencies are broken
    by being uninstalled ones.
    </para>
        <para>
          Default: greedy = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.aggressive_greedy">aggressive greedy</option>
      </term>
      <listitem>
        <para>
    Be yet more greedy; if successor of orphaned package found, and this
    successor drags no packages then upgrade the package instead of process
    its dependencies. Option value is implied by 'greedy' one by defalut.
    </para>
        <para>
          Default: aggressive greedy = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.mercy">mercy</option>
      </term>
      <listitem>
        <para>
     Be tolerant for unmatched versioned dependencies which rpm tolerates, e.g.
     package A requires capability foo >= 1.0 while package B provides "foo"
     without any version. Use with care, it may cause weird dependency errors.
    </para>
        <para>
          Default: mercy = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.suggests">suggests</option>
      </term>
      <listitem>
        <para>
    Taking into account package Suggests.
    </para>
        <para>
          Default: suggests = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.obsoletes">obsoletes</option>
      </term>
      <listitem>
        <para>
    Taking into account package Obsoletes.
    </para>
        <para>
          Default: obsoletes = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.global.conflicts">conflicts</option>
      </term>
      <listitem>
        <para>
    Taking into account package Conflicts.
    </para>
        <para>
          Default: conflicts = yes</para>
      </listitem>
    </varlistentry>
  </variablelist>
</sect2><sect2 id="configuration.source">
  <title>Parameters of [source] section</title>
  <para>
This section contains poldek's repository configuration.
Every repository is configured in its own [source] section.
</para>
  <variablelist>
    <title/>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.source.name">name</option>
      </term>
      <listitem>
        <para>
    Unique name of the repository.
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.type">type</option>
      </term>
      <listitem>
        <para>
    Type of repository index. Permitted values are 'pndir', 'pdir', 'apt', 'yum'
    and 'dir' as listed by <option>--stl</option> switch.
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.original_type">original type</option>
      </term>
      <listitem>
        <para>
    This parameter sets index original type i.e type of repository
    from what this repository is created. Default is 'dir' - means
    that directory of packages is scanned.
    </para>
        <para>
          Default: original type = dir</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.path">path</option>
      </term>
      <listitem>
        <para>
    Unique name of the repository. May be either path or URL.
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.prefix">prefix</option>
      </term>
      <listitem>
        <para>
    If package index and packages are stored in different locations then
    prefix stands for packages path.
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.douniq">douniq</option>
      </term>
      <listitem>
        <para>
    Controls visibility of multiple package instances with different EVR.
    If on, only one, highest version will be visible.
    </para>
        <para>
          Default: douniq = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.pri">pri</option>
      </term>
      <listitem>
        <para>
    Repository priority. If the same packages (equal names and EVR)
    are available in more than one source then package from highest
    prioritized source are taken. Priority is numeric value. Lower number
    means higher priority, and negative priorities are allowed.
    Priority is numeric value.
    </para>
        <para>
          Default: pri = 0</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.auto">auto</option>
      </term>
      <listitem>
        <para>
    Controling if repository index will be implicit loaded. Set it off if
    the index should be loaded on demand only, i.e. if specified directly
    by <option>--sn</option> option.
    </para>
        <para>
          Default: auto = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.autoup">autoup</option>
      </term>
      <listitem>
        <para>
    Controls if repository index will be implicit updated. Set it off if
    the index should be updated on demand only, i.e. if specified directly
    by <option>--sn</option> option.
    </para>
        <para>
          Default: autoup = yes</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.signed">signed</option>
      </term>
      <listitem>
        <para>
    Packages PGP/GPG signatures (if any) will be verified before their
    installation.
    </para>
        <para>
          Default: signed = no</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.hold">hold</option>
      </term>
      <listitem>
        <para>
    Have the same meaning as [global] parameter. Example:
    <screen>
 hold = kernel* dev
    </screen>
    </para>
        <para>
          Default: hold = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.ignore">ignore</option>
      </term>
      <listitem>
        <para>
    Have the same meaning as [global] parameter. Example:
    <screen>
 ignore = kernel*smp* dev
    </screen>
    </para>
        <para>
          Default: ignore = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.exclude_path">exclude path</option>
      </term>
      <listitem>
        <para>
    Parameter have the same meaning as [global] parameter.
    <screen>
 exclude path = usr/share/doc:usr/share/man:usr/src
    </screen>
    </para>
        <para>
          Default: exclude path = </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.lang">lang</option>
      </term>
      <listitem>
        <para>
    Preferred language of package descriptions. If not set, taken from locale
    settings. Example:
    <screen>
 lang = pl_PL:lt_LT
    </screen>
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.source.sources">sources</option>
      </term>
      <listitem>
        <para>
    Make sense for 'group' source type only. A list of names of sources.
    </para>
      </listitem>
    </varlistentry>
  </variablelist>
</sect2><sect2 id="configuration.fetcher">
  <title>Parameters of [fetcher] section</title>
  <para>
This section contains external downloaders configuration.
Each section describes one fetcher.
</para>
  <variablelist>
    <title/>
    <para/>
    <varlistentry>
      <term>
        <option id="configuration.fetcher.name">name</option>
      </term>
      <listitem>
        <para>
    Unique name of the fetcher. This is an optional parameter, if not set then
    name is taken from the "cmd" parameter value as "$(basename $cmd)".
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.fetcher.proto">proto</option>
      </term>
      <listitem>
        <para>
    Protocol or protocols supported by fetcher. Name of the protocol can be
    completely arbitrary, i.e. if you can handle protocol "foo" by writing
    a script which takes URLs in form 'foo://'.
    </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <option id="configuration.fetcher.cmd">cmd</option>
      </term>
      <listitem>
        <para>
    Parameter specifies an external command and its invoking syntax.
    The syntax of "cmd" is:
    <screen>
 cmd = COMMAND [ OPTION... ] {%d,%D}  {%p,%P}[n]
    </screen>
    Where COMMAND is the name or full path of command, OPTION is command specific
    options. Macro '%d' is replaced with cache directory, '%D' is replaced with
    'cache directory/file basename', and '%p' with file basename, %P with file full
    path (URL).  Optional suffix 'n' with %p and %P means that command can be
    invoked with multiple files at once.
    </para>
      </listitem>
    </varlistentry>
  </variablelist>
</sect2>
