<!--
doc/src/sgml/ref/pg_enc.sgml
Pgpool-II documentation
-->

<refentry id="PG-ENC">
 <indexterm zone="pg-enc">
  <primary>pg_enc</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>pg_enc</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Other Commands</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_enc</refname>
  <refpurpose>
   AES256 password encryption utility
  </refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_enc</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg choice="plain"><replaceable>-p</replaceable></arg>
  </cmdsynopsis>
  <cmdsynopsis>
   <command>pg_enc</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg choice="plain"><replaceable>password</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="R1-PG-ENC-1">
  <title>Description</title>
  <para>
   <command>pg_enc</command>
   AES256 password encryption utility.
  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>
  <para>
   <variablelist>

    <varlistentry>
     <term><option>-k <replaceable class="parameter">KEY_FILE</replaceable></option></term>
     <term><option>--key-file=<replaceable class="parameter">KEY_FILE</replaceable></option></term>
     <listitem>
      <para>
       Set the path to the encryption key file. Default is the <literal>.pgpoolkey</literal> file
       located in the users home directory, which can be overridden by the environment variable <varname>PGPOOLKEYFILE</varname>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-K <replaceable class="parameter">ENCRYPTION_KEY</replaceable></option></term>
     <term><option>--enc-key=<replaceable class="parameter">ENCRYPTION_KEY</replaceable></option></term>
     <listitem>
      <para>
       Encryption key to be used for encrypting database passwords.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-f <replaceable class="parameter">CONFIG_FILE</replaceable></option></term>
     <term><option>--config-file=<replaceable class="parameter">CONFIG_FILE</replaceable></option></term>
     <listitem>
      <para>
       Specifies the <literal>pgpool.conf</literal> file.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-i <replaceable class="parameter">INPUT_FILE</replaceable></option></term>
     <term><option>--input-file=<replaceable class="parameter">INPUT_FILE</replaceable></option></term>
     <listitem>
      <para>
       Specifies file containing username and password pairs.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-p</option></term>
     <term><option>--prompt</option></term>
     <listitem>
      <para>
       Prompt for database password using standard input.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-P</option></term>
     <term><option>--prompt-for-key</option></term>
     <listitem>
      <para>
       Prompt for encryption key using standard input.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-m</option></term>
     <term><option>--update-pass</option></term>
     <listitem>
      <para>
       Create encrypted password entry in the pool_passwd file.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-u <replaceable class="parameter">your_username</replaceable></option></term>
     <term><option>--username=<replaceable class="parameter">your_username</replaceable></option></term>
     <listitem>
      <para>
       Creates the <literal>pool_passwd</literal> entry for the database user called
       <literal>your_username</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-h</option></term>
     <term><option>--help</option></term>
     <listitem>
      <para>
       Prints the help for <literal>pg_enc</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

    <note>
     <para>
      If you are providing the password as an argument to pg_enc and the password contains a "$" character,
      you must escape it.
     </para>
     <para>
      For example, if you want to use "ABC$123" as password,
      <programlisting>
pg_enc -m -f /path/to/pgpool.conf -u username ABC\$123
      </programlisting>
     </para>
    </note>
  </para>
 </refsect1>

 <refsect1>
  <title>Example</title>
  <para>
   Here is an example output:
   <programlisting>
    pg_enc -p
    db password: [your password]
   </programlisting>
  </para>
  <para>
   or
  </para>
  <programlisting>
   ./pg_enc foo
   trying to read key from file /home/pgpool/.pgpoolkey

   jglid1QRgiCl/vfhHUDyVA==
   pool_passwd string: AESjglid1QRgiCl/vfhHUDyVA==
  </programlisting>
  <para>
   <literal>pg_enc</literal> can be used for <literal>pool_passwd</literal> passwords with:
   <programlisting>
    pg_enc -m -f /path/to/pgpool.conf -u username -p
    db password: [your password]
   </programlisting>
   which will add an entry for <literal>username</literal> with the password given.
  </para>
  <para>
   To avoid password prompt or password in command parameter,
   <literal>pg_enc</literal> can read user name:password pairs from file.
   It will add all user names and encrypted password to
   <xref linkend="guc-pool-passwd"> authentication file.
   <programlisting>
    $ cat users.txt
    username1:secretpassword1
    username2:secretpassword2

    $ pg_enc -m -f /path/to/pgpool.conf -i users.txt
    trying to read key from file /home/pgpool/.pgpoolkey
    trying to read user:password pairs from file users.text

    $ cat /path/to/pool_passwd
    username1:AESrx5QdpGyW/+4CB80KWtwhg==
    username2:AESUAdohy7nCUhWliRI9WiYQA==
   </programlisting>
  </para>

 </refsect1>

</refentry>
