doc/src/sgml/ref/pg_alterckey.sgml

<!--
doc/src/sgml/ref/pg_alterckey.sgml
PostgreSQL documentation
-->

<refentry id="app-pg_alterckey">
 <indexterm zone="app-pg_alterckey">
  <primary>pg_alterckey</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_alterckey</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_alterckey</refname>
  <refpurpose>alter the <productname>PostgreSQL</productname> cluster key</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_alterckey</command>

   <group choice="plain">
    <arg choice="plain"><option>-R</option></arg>
    <arg choice="plain"><option>--authprompt</option></arg>
   </group>

   <arg choice="plain">
    <replaceable class="parameter">old_cluster_key_command</replaceable>
    <replaceable class="parameter">new_cluster_key_command</replaceable>
   </arg>

   <arg choice="opt">
    <group choice="plain">
     <arg choice="plain"><option>-D</option></arg>
     <arg choice="plain"><option>--pgdata</option></arg>
    </group>
    <replaceable class="parameter">datadir</replaceable>
   </arg>

  </cmdsynopsis>

  <cmdsynopsis>
   <command>pg_alterckey</command>

   <group choice="opt">
    <arg choice="plain"><option>-R</option></arg>
    <arg choice="plain"><option>--authprompt</option></arg>
   </group>

   <group choice="plain">
    <arg choice="plain"><option>-r</option></arg>
    <arg choice="plain"><option>--repair</option></arg>
   </group>

   <arg choice="opt">
    <group choice="opt">
     <arg choice="plain"><option>-D</option></arg>
     <arg choice="plain"><option>--pgdata</option></arg>
    </group>
    <replaceable class="parameter">datadir</replaceable>
   </arg>

  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="r1-app-pg_alterckey-1">
  <title>Description</title>
  <para>
   <command>pg_alterckey</command> alters the cluster key used
   for cluster file encryption.  The cluster key is initially set
   during <xref linkend="app-initdb"/>.  The command can be run while the
   server is running or stopped.  The new password must be used the next
   time the server is started.
  </para>

  <para>
   <command>pg_alterckey</command> changes the key encryption key
   (<acronym>KEK</acronym>) which encrypts the data encryption keys;
   it does not change the data encryption keys.  It does this by
   decrypting each data encryption key using the <replaceable
   class="parameter">old_cluster_key_command</replaceable>,
   re-encrypting it using the <replaceable
   class="parameter">new_cluster_key_command</replaceable>, and then
   writes the result back to the cluster directory.
  </para>

  <para>
   See the <xref linkend="app-initdb"/> documentation for how to define
   the old and new passphrase commands.  You can use different executables
   for these commands, or you can use the same executable with different
   arguments to specify retrieval of the old or new key.
  </para>

  <para>
   <command>pg_alterckey</command> manages data encryption keys,
   which are critical to allowing Postgres to access its decrypted
   data.  For this reason, it is very careful to preserve these
   keys in most possible failure conditions, e.g., operating system
   failure during cluster encryption key rotation.
  </para>

  <para>
   When started, <command>pg_alterckey</command> repairs any files that
   remain from previous failures before altering the cluster encryption
   key.  During this repair phase, <command>pg_alterckey</command> will
   either roll back the cluster key or roll forward the changes that
   were previously requested.  The server will not start if repair is
   needed, though a running server is unaffected by an unrepaired cluster
   key configuration.  Therefore, if <command>pg_alterckey</command>
   fails for any reason, it is recommended you run the command with
   <option>--repair</option> to simply roll back or forward any previous
   changes.  This will report if it rolled the cluster key back or forward,
   and then run the command again to change the cluster key if needed.
  </para>

  <para>
   You can specify the data directory on the command line, or use
   the environment variable <envar>PGDATA</envar>.
  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>

   <para>
    <variablelist>
     <varlistentry>
      <term><option>-R</option></term>
      <term><option>--authprompt</option></term>
      <listitem>
       <para>
        Allows the <option>old_cluster_key_command</option> and
        <option>new_cluster_key_command</option> commands
        to prompt for a passphrase or PIN.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    Other options:

    <variablelist>
     <varlistentry>
       <term><option>-V</option></term>
       <term><option>--version</option></term>
       <listitem>
       <para>
       Print the <application>pg_alterckey</application> version and exit.
       </para>
       </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-?</option></term>
       <term><option>--help</option></term>
       <listitem>
       <para>
       Show help about <application>pg_alterckey</application> command line
       arguments, and exit.
       </para>
       </listitem>
     </varlistentry>

    </variablelist>
   </para>

 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
      Default data directory location
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PG_COLOR</envar></term>
    <listitem>
     <para>
      Specifies whether to use color in diagnostic messages. Possible values
      are <literal>always</literal>, <literal>auto</literal> and
      <literal>never</literal>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-initdb"/></member>
  </simplelist>
 </refsect1>

</refentry>