split up help messages for simpler reuse

[apt.git] / doc / apt-key.8.xml

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
]>

<refentry>
 <refentryinfo>
   &apt-author.jgunthorpe;
   &apt-author.team;
   &apt-email;
   &apt-product;
   <!-- The last update date -->
   <date>2012-06-09T00:00:00Z</date>
 </refentryinfo>

 <refmeta>
   <refentrytitle>apt-key</refentrytitle>
   <manvolnum>8</manvolnum>
   <refmiscinfo class="manual">APT</refmiscinfo>
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>apt-key</refname>
    <refpurpose>APT key management utility</refpurpose>
 </refnamediv>

 &synopsis-command-apt-key;

 <refsect1><title>Description</title>
   <para>
   <command>apt-key</command> is used to manage the list of keys used
   by apt to authenticate packages.  Packages which have been
   authenticated using these keys will be considered trusted.
   </para>
</refsect1>

<refsect1><title>Commands</title>
   <variablelist>
     <varlistentry><term><option>add</option> <option>&synopsis-param-filename;</option></term>
     <listitem>
     <para>
       Add a new key to the list of trusted keys.
       The key is read from the filename given with the parameter
       &synopsis-param-filename; or if the filename is <literal>-</literal>
       from standard input.
     </para>
     <para>
     It is critical that keys added manually via <command>apt-key</command> are
     verified to belong to the owner of the repositories they claim to be for
     otherwise the &apt-secure; infrastructure is completely undermined.
     </para>
     </listitem>
     </varlistentry>

     <varlistentry><term><option>del</option> <option>&synopsis-param-keyid;</option></term>
     <listitem>
     <para>

       Remove a key from the list of trusted keys.

     </para>

     </listitem>
     </varlistentry>

     <varlistentry><term><option>export</option> <option>&synopsis-param-keyid;</option></term>
     <listitem>
     <para>

        Output the key &synopsis-param-keyid; to standard output.

     </para>

     </listitem>
     </varlistentry>

     <varlistentry><term><option>exportall</option></term>
     <listitem>
     <para>

        Output all trusted keys to standard output.

     </para>

     </listitem>
     </varlistentry>

     <varlistentry><term><option>list</option></term>
     <listitem>
     <para>

       List trusted keys.

     </para>

     </listitem>
     </varlistentry>
     
     <varlistentry><term><option>finger</option></term>
     <listitem>
     <para>

     List fingerprints of trusted keys.

     </para>

     </listitem>
     </varlistentry>
     
     <varlistentry><term><option>adv</option></term>
     <listitem>
     <para>
     Pass advanced options to gpg. With <command>adv --recv-key</command> you
     can e.g. download key from keyservers directly into the the trusted set of
     keys. Note that there are <emphasis>no</emphasis> checks performed, so it is
     easy to completely undermine the &apt-secure; infrastructure if used without
     care.
     </para>

     </listitem>
     </varlistentry>

     <varlistentry><term><option>update</option></term>
     <listitem>
     <para>

       Update the local keyring with the archive keyring and remove from
       the local keyring the archive keys which are no longer valid.
       The archive keyring is shipped in the <literal>archive-keyring</literal> package of your
       distribution, e.g. the &keyring-package; package in &keyring-distro;.

     </para>

     </listitem>
     </varlistentry>
     
     <varlistentry><term><option>net-update</option></term>
     <listitem>
     <para>

       Perform an update working similarly to the <command>update</command> command above,
       but get the archive keyring from a URI instead and validate it against a master key.

       This requires an installed &wget; and an APT build configured to have
       a server to fetch from and a master keyring to validate.

       APT in Debian does not support this command, relying on
       <command>update</command> instead, but Ubuntu's APT does.

     </para>

     </listitem>
     </varlistentry>
   </variablelist>
</refsect1>

 <refsect1><title>Options</title>
<para>Note that options need to be defined before the commands described in the previous section.</para>
   <variablelist>
      <varlistentry><term><option>--keyring</option> <option>&synopsis-param-filename;</option></term>
      <listitem><para>With this option it is possible to specify a particular keyring
      file the command should operate on. The default is that a command is executed
      on the <filename>trusted.gpg</filename> file as well as on all parts in the
      <filename>trusted.gpg.d</filename> directory, though <filename>trusted.gpg</filename>
      is the primary keyring which means that e.g. new keys are added to this one.
      </para></listitem>
      </varlistentry>
   </variablelist>
 </refsect1>

 <refsect1><title>Files</title>
   <variablelist>

     &file-trustedgpg;

     <varlistentry><term><filename>/etc/apt/trustdb.gpg</filename></term>
     <listitem><para>Local trust database of archive keys.</para></listitem>
     </varlistentry>

     <varlistentry><term>&keyring-filename;</term>
     <listitem><para>Keyring of &keyring-distro; archive trusted keys.</para></listitem>
     </varlistentry>

     <varlistentry><term>&keyring-removed-filename;</term>
     <listitem><para>Keyring of &keyring-distro; archive removed trusted keys.</para></listitem>
     </varlistentry>

   </variablelist>

</refsect1>

<refsect1><title>See Also</title>
<para>
&apt-get;, &apt-secure;
</para>
</refsect1>

 &manbugs;
 &manauthor;

</refentry>