X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/81460e32961bb0b9922bf8a1a27d87705d8c3e51..15d9f7e76020775fc87f2b2546ba7570c58e8111:/doc/sources.list.5.xml

diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
index 8506017ad..4eb3c0ba0 100644
--- a/doc/sources.list.5.xml
+++ b/doc/sources.list.5.xml
@@ -36,7 +36,7 @@
       designed to support any number of active sources and a variety of source
       media. The files list one source per line (one line style) or contain multiline
       stanzas defining one or more sources per stanza (deb822 style), with the
-      most preferred source listed first. The information available from the
+      most preferred source listed first (in case a single version is available from more than one source). The information available from the
       configured sources is acquired by <command>apt-get update</command> (or
       by an equivalent command from another APT front-end).
    </para>
@@ -202,41 +202,87 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
        APT versions.
 
        <itemizedlist>
-	  <listitem><para><literal>Architectures</literal>
-		(<literal>arch</literal>) is a multivalue option defining for
+	  <listitem><para><option>Architectures</option>
+		(<option>arch</option>) is a multivalue option defining for
 		which architectures information should be downloaded. If this
 		option isn't set the default is all architectures as defined by
-		the <literal>APT::Architectures</literal> config option.
+		the <option>APT::Architectures</option> config option.
 	  </para></listitem>
 
-	  <listitem><para><literal>Languages</literal>
-		(<literal>lang</literal>) is a multivalue option defining for
+	  <listitem><para><option>Languages</option>
+		(<option>lang</option>) is a multivalue option defining for
 		which languages information like translated package
 		descriptions should be downloaded.  If this option isn't set
 		the default is all languages as defined by the
-		<literal>Acquire::Languages</literal> config option.
+		<option>Acquire::Languages</option> config option.
 	  </para></listitem>
 
-	  <listitem><para><literal>Targets</literal>
-		(<literal>target</literal>) is a multivalue option defining
+	  <listitem><para><option>Targets</option>
+		(<option>target</option>) is a multivalue option defining
 		which download targets apt will try to acquire from this
 		source. If not specified, the default set is defined by the
-		<literal>APT::Acquire::Targets</literal> configuration scope.
+		<option>Acquire::IndexTargets</option> configuration scope.
+		Aditionally, specific targets can be enabled or disabled by
+		using the identifier as field name instead of using this
+		multivalue option.
+	  </para></listitem>
+       </itemizedlist>
+
+       Further more, there are options which if set effect
+       <emphasis>all</emphasis> sources with the same URI and Suite, so they
+       have to be set on all such entries and can not be varied between
+       different components. APT will try to detect and error out on such
+       anomalies.
+
+       <itemizedlist>
+	  <listitem><para><option>Signed-By</option> (<option>signed-by</option>)
+		is either an absolute path to a keyring file (has to be
+		accessible and readable for the <literal>_apt</literal> user,
+		so ensure everyone has read-permissions on the file) or a
+		fingerprint of a key in either the
+		<filename>trusted.gpg</filename> keyring or in one of the
+		keyrings in the <filename>trusted.gpg.d/</filename> directory
+		(see <command>apt-key fingerprint</command>). If the option is
+		set only the key(s) in this keyring or only the key with this
+		fingerprint is used for the &apt-secure; verification of this
+		repository. Otherwise all keys in the trusted keyrings are
+		considered valid signers for this repository.
+	  </para></listitem>
+
+	  <listitem><para><option>Check-Valid-Until</option> (<option>check-valid-until</option>)
+		is a yes/no value which controls if APT should try to detect
+		replay attacks. A repository creator can declare until then the
+		data provided in the repository should be considered valid and
+		if this time is reached, but no new data is provided the data
+		is considered expired and an error is raised.  Beside
+		increasing security as a malicious attacker can't sent old data
+		forever denying a user to be able to upgrade to a new version,
+		this also helps users identify mirrors which are no longer
+		updated. Some repositories like historic archives aren't
+		updated anymore by design through, so this check can be
+		disabled by setting this option to <literal>no</literal>.
+		Defaults to the value of configuration option
+		<option>Acquire::Check-Valid-Until</option> which itself
+		defaults to <literal>yes</literal>.
 	  </para></listitem>
 
-	  <listitem><para><literal>Trusted</literal> (<literal>trusted</literal>)
-		is a tri-state value which defaults to APT deciding if a source
-		is considered trusted or if warnings should be raised before e.g.
-		packages are installed from this source. This option can be used
-		to override this decision either with the value <literal>yes</literal>,
-		which lets APT consider this source always as a trusted source
-		even if it has no or fails authentication checks by disabling parts
-		of &apt-secure; and should therefore only be used in a local and trusted
-		context (if at all) as otherwise security is breached. The opposite
-		can be achieved with the value no, which causes the source to be handled
-		as untrusted even if the authentication checks passed successfully.
-		The default value can't be set explicitly.
+	  <listitem><para><option>Valid-Until-Min</option>
+		(<option>check-valid-min</option>) and
+		<option>Valid-Until-Max</option>
+		(<option>valid-until-max</option>) can be used to raise or
+		lower the time period in seconds in which the data from this
+		repository is considered valid. -Max can be especially useful
+		if the repository provides no Valid-Until field on its Release
+		file to set your own value, while -Min can be used to increase
+		the valid time on seldom updated (local) mirrors of a more
+		frequently updated but less accessible archive (which is in the
+		sources.list as well) instead of disabling the check entirely.
+		Default to the value of the configuration options
+		<option>Acquire::Min-ValidTime</option> and
+		<option>Acquire::Max-ValidTime</option> which are both unset by
+		default.
 	  </para></listitem>
+
        </itemizedlist>
 
     </para>