All of lore.kernel.org
 help / color / mirror / Atom feed
From: xiubli@redhat.com
To: idryomov@gmail.com, ceph-devel@vger.kernel.org
Cc: jlayton@kernel.org, vshankar@redhat.com, mchangir@redhat.com,
	lhenriques@suse.de, Xiubo Li <xiubli@redhat.com>
Subject: [PATCH v17 48/71] ceph: add infrastructure for file encryption and decryption
Date: Thu, 23 Mar 2023 14:55:02 +0800	[thread overview]
Message-ID: <20230323065525.201322-49-xiubli@redhat.com> (raw)
In-Reply-To: <20230323065525.201322-1-xiubli@redhat.com>

From: Jeff Layton <jlayton@kernel.org>

...and allow test_dummy_encryption to bypass content encryption
if mounted with test_dummy_encryption=clear.

Reviewed-by: Xiubo Li <xiubli@redhat.com>
Signed-off-by: Jeff Layton <jlayton@kernel.org>
---
 fs/ceph/crypto.c | 177 +++++++++++++++++++++++++++++++++++++++++++++++
 fs/ceph/crypto.h |  71 +++++++++++++++++++
 fs/ceph/super.c  |   6 ++
 fs/ceph/super.h  |   1 +
 4 files changed, 255 insertions(+)

diff --git a/fs/ceph/crypto.c b/fs/ceph/crypto.c
index fe47fbdaead9..35e292045e9d 100644
--- a/fs/ceph/crypto.c
+++ b/fs/ceph/crypto.c
@@ -9,6 +9,7 @@
 #include <linux/ceph/ceph_debug.h>
 #include <linux/xattr.h>
 #include <linux/fscrypt.h>
+#include <linux/ceph/striper.h>
 
 #include "super.h"
 #include "mds_client.h"
@@ -354,3 +355,179 @@ int ceph_fscrypt_prepare_readdir(struct inode *dir)
 	}
 	return 0;
 }
+
+int ceph_fscrypt_decrypt_block_inplace(const struct inode *inode,
+				  struct page *page, unsigned int len,
+				  unsigned int offs, u64 lblk_num)
+{
+	struct ceph_mount_options *opt = ceph_inode_to_client(inode)->mount_options;
+
+	if (opt->flags & CEPH_MOUNT_OPT_DUMMY_ENC_CLEAR)
+		return 0;
+
+	dout("%s: len %u offs %u blk %llu\n", __func__, len, offs, lblk_num);
+	return fscrypt_decrypt_block_inplace(inode, page, len, offs, lblk_num);
+}
+
+int ceph_fscrypt_encrypt_block_inplace(const struct inode *inode,
+				  struct page *page, unsigned int len,
+				  unsigned int offs, u64 lblk_num, gfp_t gfp_flags)
+{
+	struct ceph_mount_options *opt = ceph_inode_to_client(inode)->mount_options;
+
+	if (opt->flags & CEPH_MOUNT_OPT_DUMMY_ENC_CLEAR)
+		return 0;
+
+	dout("%s: len %u offs %u blk %llu\n", __func__, len, offs, lblk_num);
+	return fscrypt_encrypt_block_inplace(inode, page, len, offs, lblk_num, gfp_flags);
+}
+
+/**
+ * ceph_fscrypt_decrypt_pages - decrypt an array of pages
+ * @inode: pointer to inode associated with these pages
+ * @page: pointer to page array
+ * @off: offset into the file that the read data starts
+ * @len: max length to decrypt
+ *
+ * Decrypt an array of fscrypt'ed pages and return the amount of
+ * data decrypted. Any data in the page prior to the start of the
+ * first complete block in the read is ignored. Any incomplete
+ * crypto blocks at the end of the array are ignored (and should
+ * probably be zeroed by the caller).
+ *
+ * Returns the length of the decrypted data or a negative errno.
+ */
+int ceph_fscrypt_decrypt_pages(struct inode *inode, struct page **page, u64 off, int len)
+{
+	int i, num_blocks;
+	u64 baseblk = off >> CEPH_FSCRYPT_BLOCK_SHIFT;
+	int ret = 0;
+
+	/*
+	 * We can't deal with partial blocks on an encrypted file, so mask off
+	 * the last bit.
+	 */
+	num_blocks = ceph_fscrypt_blocks(off, len & CEPH_FSCRYPT_BLOCK_MASK);
+
+	/* Decrypt each block */
+	for (i = 0; i < num_blocks; ++i) {
+		int blkoff = i << CEPH_FSCRYPT_BLOCK_SHIFT;
+		int pgidx = blkoff >> PAGE_SHIFT;
+		unsigned int pgoffs = offset_in_page(blkoff);
+		int fret;
+
+		fret = ceph_fscrypt_decrypt_block_inplace(inode, page[pgidx],
+				CEPH_FSCRYPT_BLOCK_SIZE, pgoffs,
+				baseblk + i);
+		if (fret < 0) {
+			if (ret == 0)
+				ret = fret;
+			break;
+		}
+		ret += CEPH_FSCRYPT_BLOCK_SIZE;
+	}
+	return ret;
+}
+
+/**
+ * ceph_fscrypt_decrypt_extents: decrypt received extents in given buffer
+ * @inode: inode associated with pages being decrypted
+ * @page: pointer to page array
+ * @off: offset into the file that the data in page[0] starts
+ * @map: pointer to extent array
+ * @ext_cnt: length of extent array
+ *
+ * Given an extent map and a page array, decrypt the received data in-place,
+ * skipping holes. Returns the offset into buffer of end of last decrypted
+ * block.
+ */
+int ceph_fscrypt_decrypt_extents(struct inode *inode, struct page **page, u64 off,
+				 struct ceph_sparse_extent *map, u32 ext_cnt)
+{
+	int i, ret = 0;
+	struct ceph_inode_info *ci = ceph_inode(inode);
+	u64 objno, objoff;
+	u32 xlen;
+
+	/* Nothing to do for empty array */
+	if (ext_cnt == 0) {
+		dout("%s: empty array, ret 0\n", __func__);
+		return 0;
+	}
+
+	ceph_calc_file_object_mapping(&ci->i_layout, off, map[0].len,
+				      &objno, &objoff, &xlen);
+
+	for (i = 0; i < ext_cnt; ++i) {
+		struct ceph_sparse_extent *ext = &map[i];
+		int pgsoff = ext->off - objoff;
+		int pgidx = pgsoff >> PAGE_SHIFT;
+		int fret;
+
+		if ((ext->off | ext->len) & ~CEPH_FSCRYPT_BLOCK_MASK) {
+			pr_warn("%s: bad encrypted sparse extent idx %d off %llx len %llx\n",
+				__func__, i, ext->off, ext->len);
+			return -EIO;
+		}
+		fret = ceph_fscrypt_decrypt_pages(inode, &page[pgidx],
+						 off + pgsoff, ext->len);
+		dout("%s: [%d] 0x%llx~0x%llx fret %d\n", __func__, i,
+				ext->off, ext->len, fret);
+		if (fret < 0) {
+			if (ret == 0)
+				ret = fret;
+			break;
+		}
+		ret = pgsoff + fret;
+	}
+	dout("%s: ret %d\n", __func__, ret);
+	return ret;
+}
+
+/**
+ * ceph_fscrypt_encrypt_pages - encrypt an array of pages
+ * @inode: pointer to inode associated with these pages
+ * @page: pointer to page array
+ * @off: offset into the file that the data starts
+ * @len: max length to encrypt
+ * @gfp: gfp flags to use for allocation
+ *
+ * Decrypt an array of cleartext pages and return the amount of
+ * data encrypted. Any data in the page prior to the start of the
+ * first complete block in the read is ignored. Any incomplete
+ * crypto blocks at the end of the array are ignored.
+ *
+ * Returns the length of the encrypted data or a negative errno.
+ */
+int ceph_fscrypt_encrypt_pages(struct inode *inode, struct page **page, u64 off,
+				int len, gfp_t gfp)
+{
+	int i, num_blocks;
+	u64 baseblk = off >> CEPH_FSCRYPT_BLOCK_SHIFT;
+	int ret = 0;
+
+	/*
+	 * We can't deal with partial blocks on an encrypted file, so mask off
+	 * the last bit.
+	 */
+	num_blocks = ceph_fscrypt_blocks(off, len & CEPH_FSCRYPT_BLOCK_MASK);
+
+	/* Encrypt each block */
+	for (i = 0; i < num_blocks; ++i) {
+		int blkoff = i << CEPH_FSCRYPT_BLOCK_SHIFT;
+		int pgidx = blkoff >> PAGE_SHIFT;
+		unsigned int pgoffs = offset_in_page(blkoff);
+		int fret;
+
+		fret = ceph_fscrypt_encrypt_block_inplace(inode, page[pgidx],
+				CEPH_FSCRYPT_BLOCK_SIZE, pgoffs,
+				baseblk + i, gfp);
+		if (fret < 0) {
+			if (ret == 0)
+				ret = fret;
+			break;
+		}
+		ret += CEPH_FSCRYPT_BLOCK_SIZE;
+	}
+	return ret;
+}
diff --git a/fs/ceph/crypto.h b/fs/ceph/crypto.h
index 80acb23d0bb4..887f191cc423 100644
--- a/fs/ceph/crypto.h
+++ b/fs/ceph/crypto.h
@@ -100,6 +100,40 @@ int ceph_fname_to_usr(const struct ceph_fname *fname, struct fscrypt_str *tname,
 			struct fscrypt_str *oname, bool *is_nokey);
 int ceph_fscrypt_prepare_readdir(struct inode *dir);
 
+static inline unsigned int ceph_fscrypt_blocks(u64 off, u64 len)
+{
+	/* crypto blocks cannot span more than one page */
+	BUILD_BUG_ON(CEPH_FSCRYPT_BLOCK_SHIFT > PAGE_SHIFT);
+
+	return ((off+len+CEPH_FSCRYPT_BLOCK_SIZE-1) >> CEPH_FSCRYPT_BLOCK_SHIFT) -
+		(off >> CEPH_FSCRYPT_BLOCK_SHIFT);
+}
+
+/*
+ * If we have an encrypted inode then we must adjust the offset and
+ * range of the on-the-wire read to cover an entire encryption block.
+ * The copy will be done using the original offset and length, after
+ * we've decrypted the result.
+ */
+static inline void ceph_fscrypt_adjust_off_and_len(struct inode *inode, u64 *off, u64 *len)
+{
+	if (IS_ENCRYPTED(inode)) {
+		*len = ceph_fscrypt_blocks(*off, *len) * CEPH_FSCRYPT_BLOCK_SIZE;
+		*off &= CEPH_FSCRYPT_BLOCK_MASK;
+	}
+}
+
+int ceph_fscrypt_decrypt_block_inplace(const struct inode *inode,
+				  struct page *page, unsigned int len,
+				  unsigned int offs, u64 lblk_num);
+int ceph_fscrypt_encrypt_block_inplace(const struct inode *inode,
+				  struct page *page, unsigned int len,
+				  unsigned int offs, u64 lblk_num, gfp_t gfp_flags);
+int ceph_fscrypt_decrypt_pages(struct inode *inode, struct page **page, u64 off, int len);
+int ceph_fscrypt_decrypt_extents(struct inode *inode, struct page **page, u64 off,
+				 struct ceph_sparse_extent *map, u32 ext_cnt);
+int ceph_fscrypt_encrypt_pages(struct inode *inode, struct page **page, u64 off,
+				int len, gfp_t gfp);
 #else /* CONFIG_FS_ENCRYPTION */
 
 static inline void ceph_fscrypt_set_ops(struct super_block *sb)
@@ -157,6 +191,43 @@ static inline int ceph_fscrypt_prepare_readdir(struct inode *dir)
 {
 	return 0;
 }
+
+static inline void ceph_fscrypt_adjust_off_and_len(struct inode *inode, u64 *off, u64 *len)
+{
+}
+
+static inline int ceph_fscrypt_decrypt_block_inplace(const struct inode *inode,
+					  struct page *page, unsigned int len,
+					  unsigned int offs, u64 lblk_num)
+{
+	return 0;
+}
+
+static inline int ceph_fscrypt_encrypt_block_inplace(const struct inode *inode,
+				  struct page *page, unsigned int len,
+				  unsigned int offs, u64 lblk_num, gfp_t gfp_flags)
+{
+	return 0;
+}
+
+static inline int ceph_fscrypt_decrypt_pages(struct inode *inode, struct page **page,
+					     u64 off, int len)
+{
+	return 0;
+}
+
+static inline int ceph_fscrypt_decrypt_extents(struct inode *inode, struct page **page,
+					u64 off, struct ceph_sparse_extent *map,
+					u32 ext_cnt)
+{
+	return 0;
+}
+
+static inline int ceph_fscrypt_encrypt_pages(struct inode *inode, struct page **page,
+					     u64 off, int len, gfp_t gfp)
+{
+	return 0;
+}
 #endif /* CONFIG_FS_ENCRYPTION */
 
 #endif
diff --git a/fs/ceph/super.c b/fs/ceph/super.c
index b9dd2fa36d8b..4b0a070d5c6d 100644
--- a/fs/ceph/super.c
+++ b/fs/ceph/super.c
@@ -591,6 +591,12 @@ static int ceph_parse_mount_param(struct fs_context *fc,
 		break;
 	case Opt_test_dummy_encryption:
 #ifdef CONFIG_FS_ENCRYPTION
+		/* HACK: allow for cleartext "encryption" in files for testing */
+		if (param->string && !strcmp(param->string, "clear")) {
+			fsopt->flags |= CEPH_MOUNT_OPT_DUMMY_ENC_CLEAR;
+			kfree(param->string);
+			param->string = NULL;
+		}
 		fscrypt_free_dummy_policy(&fsopt->dummy_enc_policy);
 		ret = fscrypt_parse_test_dummy_encryption(param,
 						&fsopt->dummy_enc_policy);
diff --git a/fs/ceph/super.h b/fs/ceph/super.h
index f4659b2a4731..e23bfd9191b3 100644
--- a/fs/ceph/super.h
+++ b/fs/ceph/super.h
@@ -44,6 +44,7 @@
 #define CEPH_MOUNT_OPT_ASYNC_DIROPS    (1<<15) /* allow async directory ops */
 #define CEPH_MOUNT_OPT_NOPAGECACHE     (1<<16) /* bypass pagecache altogether */
 #define CEPH_MOUNT_OPT_SPARSEREAD      (1<<17) /* always do sparse reads */
+#define CEPH_MOUNT_OPT_DUMMY_ENC_CLEAR (1<<18) /* don't actually encrypt content */
 
 #define CEPH_MOUNT_OPT_DEFAULT			\
 	(CEPH_MOUNT_OPT_DCACHE |		\
-- 
2.31.1


  parent reply	other threads:[~2023-03-23  7:00 UTC|newest]

Thread overview: 77+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-03-23  6:54 [PATCH v17 00/71] ceph+fscrypt: full support xiubli
2023-03-23  6:54 ` [PATCH v17 01/71] libceph: add spinlock around osd->o_requests xiubli
2023-03-23  6:54 ` [PATCH v17 02/71] libceph: define struct ceph_sparse_extent and add some helpers xiubli
2023-03-23  6:54 ` [PATCH v17 03/71] libceph: add sparse read support to msgr2 crc state machine xiubli
2023-03-23  6:54 ` [PATCH v17 04/71] libceph: add sparse read support to OSD client xiubli
2023-03-23  6:54 ` [PATCH v17 05/71] libceph: support sparse reads on msgr2 secure codepath xiubli
2023-03-23  6:54 ` [PATCH v17 06/71] libceph: add sparse read support to msgr1 xiubli
2023-03-23  6:54 ` [PATCH v17 07/71] ceph: add new mount option to enable sparse reads xiubli
2023-03-23  6:54 ` [PATCH v17 08/71] ceph: preallocate inode for ops that may create one xiubli
2023-03-23  6:54 ` [PATCH v17 09/71] ceph: make ceph_msdc_build_path use ref-walk xiubli
2023-03-23  6:54 ` [PATCH v17 10/71] libceph: add new iov_iter-based ceph_msg_data_type and ceph_osd_data_type xiubli
2023-03-23  6:54 ` [PATCH v17 11/71] ceph: use osd_req_op_extent_osd_iter for netfs reads xiubli
2023-03-23  6:54 ` [PATCH v17 12/71] ceph: fscrypt_auth handling for ceph xiubli
2023-03-23  6:54 ` [PATCH v17 13/71] ceph: ensure that we accept a new context from MDS for new inodes xiubli
2023-03-23  6:54 ` [PATCH v17 14/71] ceph: add support for fscrypt_auth/fscrypt_file to cap messages xiubli
2023-03-23  6:54 ` [PATCH v17 15/71] ceph: implement -o test_dummy_encryption mount option xiubli
2023-03-23  6:54 ` [PATCH v17 16/71] ceph: decode alternate_name in lease info xiubli
2023-03-23  6:54 ` [PATCH v17 17/71] ceph: add fscrypt ioctls xiubli
2023-03-23  6:54 ` [PATCH v17 18/71] ceph: make the ioctl cmd more readable in debug log xiubli
2023-03-23  6:54 ` [PATCH v17 19/71] ceph: add base64 endcoding routines for encrypted names xiubli
2023-03-23  6:54 ` [PATCH v17 20/71] ceph: add encrypted fname handling to ceph_mdsc_build_path xiubli
2023-03-23  6:54 ` [PATCH v17 21/71] ceph: send altname in MClientRequest xiubli
2023-03-23  6:54 ` [PATCH v17 22/71] ceph: encode encrypted name in dentry release xiubli
2023-03-23  6:54 ` [PATCH v17 23/71] ceph: properly set DCACHE_NOKEY_NAME flag in lookup xiubli
2023-03-23  6:54 ` [PATCH v17 24/71] ceph: set DCACHE_NOKEY_NAME in atomic open xiubli
2023-03-23  6:54 ` [PATCH v17 25/71] ceph: make d_revalidate call fscrypt revalidator for encrypted dentries xiubli
2023-03-23  6:54 ` [PATCH v17 26/71] ceph: add helpers for converting names for userland presentation xiubli
2023-03-23  6:54 ` [PATCH v17 27/71] ceph: fix base64 encoded name's length check in ceph_fname_to_usr() xiubli
2023-03-23  6:54 ` [PATCH v17 28/71] ceph: add fscrypt support to ceph_fill_trace xiubli
2023-03-23  6:54 ` [PATCH v17 29/71] ceph: pass the request to parse_reply_info_readdir() xiubli
2023-03-23  6:54 ` [PATCH v17 30/71] ceph: add ceph_encode_encrypted_dname() helper xiubli
2023-03-23  6:54 ` [PATCH v17 31/71] ceph: add support to readdir for encrypted filenames xiubli
2023-03-23  6:54 ` [PATCH v17 32/71] ceph: create symlinks with encrypted and base64-encoded targets xiubli
2023-03-23  6:54 ` [PATCH v17 33/71] ceph: make ceph_get_name decrypt filenames xiubli
2023-03-23  6:54 ` [PATCH v17 34/71] ceph: add a new ceph.fscrypt.auth vxattr xiubli
2023-03-23  6:54 ` [PATCH v17 35/71] ceph: add some fscrypt guardrails xiubli
2023-03-23  6:54 ` [PATCH v17 36/71] ceph: allow encrypting a directory while not having Ax caps xiubli
2023-03-23  6:54 ` [PATCH v17 37/71] ceph: mark directory as non-complete after loading key xiubli
2023-03-23  6:54 ` [PATCH v17 38/71] ceph: don't allow changing layout on encrypted files/directories xiubli
2023-03-23  6:54 ` [PATCH v17 39/71] libceph: add CEPH_OSD_OP_ASSERT_VER support xiubli
2023-03-23  6:54 ` [PATCH v17 40/71] ceph: size handling for encrypted inodes in cap updates xiubli
2023-03-23  6:54 ` [PATCH v17 41/71] ceph: fscrypt_file field handling in MClientRequest messages xiubli
2023-03-23  6:54 ` [PATCH v17 42/71] ceph: get file size from fscrypt_file when present in inode traces xiubli
2023-03-23  6:54 ` [PATCH v17 43/71] ceph: handle fscrypt fields in cap messages from MDS xiubli
2023-03-23  6:54 ` [PATCH v17 44/71] ceph: update WARN_ON message to pr_warn xiubli
2023-03-23  6:54 ` [PATCH v17 45/71] ceph: add __ceph_get_caps helper support xiubli
2023-03-23  6:55 ` [PATCH v17 46/71] ceph: add __ceph_sync_read " xiubli
2023-03-23  6:55 ` [PATCH v17 47/71] ceph: add object version support for sync read xiubli
2023-03-23  6:55 ` xiubli [this message]
2023-03-23  6:55 ` [PATCH v17 49/71] ceph: add truncate size handling support for fscrypt xiubli
2023-03-23  6:55 ` [PATCH v17 50/71] libceph: allow ceph_osdc_new_request to accept a multi-op read xiubli
2023-03-23  6:55 ` [PATCH v17 51/71] ceph: disable fallocate for encrypted inodes xiubli
2023-03-23  6:55 ` [PATCH v17 52/71] ceph: disable copy offload on " xiubli
2023-03-23  6:55 ` [PATCH v17 53/71] ceph: don't use special DIO path for " xiubli
2023-03-23  6:55 ` [PATCH v17 54/71] ceph: align data in pages in ceph_sync_write xiubli
2023-03-23  6:55 ` [PATCH v17 55/71] ceph: add read/modify/write to ceph_sync_write xiubli
2023-03-23  6:55 ` [PATCH v17 56/71] ceph: plumb in decryption during sync reads xiubli
2023-03-23  6:55 ` [PATCH v17 57/71] ceph: add fscrypt decryption support to ceph_netfs_issue_op xiubli
2023-03-23  6:55 ` [PATCH v17 58/71] ceph: set i_blkbits to crypto block size for encrypted inodes xiubli
2023-03-23  6:55 ` [PATCH v17 59/71] ceph: add encryption support to writepage xiubli
2023-03-23  6:55 ` [PATCH v17 60/71] ceph: fscrypt support for writepages xiubli
2023-03-23  6:55 ` [PATCH v17 61/71] ceph: invalidate pages when doing direct/sync writes xiubli
2023-03-23  6:55 ` [PATCH v17 62/71] ceph: add support for encrypted snapshot names xiubli
2023-03-23  6:55 ` [PATCH v17 63/71] ceph: add support for handling " xiubli
2023-03-23  6:55 ` [PATCH v17 64/71] ceph: update documentation regarding snapshot naming limitations xiubli
2023-03-23  6:55 ` [PATCH v17 65/71] ceph: prevent snapshots to be created in encrypted locked directories xiubli
2023-03-23  6:55 ` [PATCH v17 66/71] ceph: report STATX_ATTR_ENCRYPTED on encrypted inodes xiubli
2023-03-23  6:55 ` [PATCH v17 67/71] libceph: defer removing the req from osdc just after req->r_callback xiubli
2023-03-23  6:55 ` [PATCH v17 68/71] ceph: drop the messages from MDS when unmounting xiubli
2023-03-30  4:51   ` Xiubo Li
2023-03-23  6:55 ` [PATCH v17 69/71] ceph: fix updating the i_truncate_pagecache_size for fscrypt xiubli
2023-03-23  6:55 ` [PATCH v17 70/71] ceph: switch ceph_open() to use new fscrypt helper xiubli
2023-03-23  6:55 ` [PATCH v17 71/71] ceph: switch ceph_open_atomic() to use the " xiubli
2023-04-03 14:28 ` [PATCH v17 00/71] ceph+fscrypt: full support Luís Henriques
2023-04-04  0:42   ` Xiubo Li
2023-04-12  8:43     ` Venky Shankar
2023-04-12 10:18       ` Xiubo Li

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20230323065525.201322-49-xiubli@redhat.com \
    --to=xiubli@redhat.com \
    --cc=ceph-devel@vger.kernel.org \
    --cc=idryomov@gmail.com \
    --cc=jlayton@kernel.org \
    --cc=lhenriques@suse.de \
    --cc=mchangir@redhat.com \
    --cc=vshankar@redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.