diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml
index 8bd5f74178e8d70e3b60093900c1223796b92257..a505707cc0112edc47181ad532e8064fa61ac24f 100644
--- a/doc/src/sgml/pgupgrade.sgml
+++ b/doc/src/sgml/pgupgrade.sgml
@@ -256,7 +256,8 @@ gmake prefix=/usr/local/pgsql.new install
      so you might want to set authentication to <literal>trust</> in
      <filename>pg_hba.conf</>, or if using <literal>md5</> authentication,
      use a <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">)
-     to avoid being prompted repeatedly for a password.
+     to avoid being prompted repeatedly for a password.  Also make sure
+     pg_upgrade is the only program that can connect to the clusters.
     </para>
    </step>
 
@@ -295,9 +296,11 @@ NET STOP pgsql-8.3  (<productname>PostgreSQL</> 8.3 and older used a different s
      data and executable (<filename>bin</>) directories. You can also specify separate
      user and port values, and whether you want the data linked instead of
      copied (the default). If you use linking, the upgrade will be much
-     faster (no data copying), but you will no longer be able to access your
-     old cluster once you start the new cluster after the upgrade. See
-     <literal>pg_upgrade --help</> for a full list of options.
+     faster (hard link data files rather than copying them), but you
+     will no longer be able to access your old cluster once you start
+     the new cluster after the upgrade.  Link mode also requires that the
+     old and new cluster data directories be in the same file system.
+     See <literal>pg_upgrade --help</> for a full list of options.
     </para>
 
     <para>