[QUEUED scylla next] doc: move the documentation from the scylla-docs repo
168 views
Skip to first unread message
Commit Bot
<bot@cloudius-systems.com>Jul 11, 2022, 8:30:23 AM7/11/22
to scylladb-dev@googlegroups.com, Anna Stuchlik
From: Anna Stuchlik <anna.s...@scylladb.com>
Committer: Anna Stuchlik <anna.s...@scylladb.com>
Branch: next
doc: move the documentation from the scylla-docs repo
---
diff --git a/docs/_static/img/mascots/scylla-cloud.svg b/docs/_static/img/mascots/scylla-cloud.svg
--- a/docs/_static/img/mascots/scylla-cloud.svg
+++ b/docs/_static/img/mascots/scylla-cloud.svg
@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="11.07 9.95 339.72 238.43"><defs><style>.cls-1,.cls-5,.cls-7,.cls-8{fill:#fff;}.cls-2,.cls-6{fill:#3b2d55;}.cls-3,.cls-4{fill:#57d1e5;}.cls-3,.cls-5,.cls-6,.cls-7,.cls-8{stroke:#3b2d55;}.cls-3,.cls-5,.cls-7,.cls-8{stroke-linecap:round;stroke-linejoin:round;}.cls-3,.cls-5{stroke-width:3.73px;}.cls-6{stroke-miterlimit:10;stroke-width:1.38px;}.cls-7{stroke-width:3.11px;}.cls-8{stroke-width:3.95px;}</style></defs><title>scylla-cloud</title><path class="cls-1" d="M81.4,125h-.18a17.09,17.09,0,0,1-.41-34.16v-.38A34.23,34.23,0,0,1,122.88,57.2a51.12,51.12,0,0,1,101.49-.54,34.46,34.46,0,0,1,5.06-.37,34.11,34.11,0,0,1,29.65,17.16c.61,0,1.19-.07,1.75-.07a25.83,25.83,0,0,1,0,51.65H81.4Z"/><path class="cls-2" d="M173.66,14a49.16,49.16,0,0,1,49,45A32.2,32.2,0,0,1,258,75.54a24.21,24.21,0,0,1,2.85-.19,23.85,23.85,0,0,1,0,47.7H81.4a15.12,15.12,0,0,1,.12-30.23c.46,0,.92,0,1.36.07-.06-.8-.1-1.6-.1-2.41a32.23,32.23,0,0,1,41.85-30.75,49.15,49.15,0,0,1,49-45.76m0-4A53.11,53.11,0,0,0,121.2,54.84a36.63,36.63,0,0,0-6.2-.53A36.21,36.21,0,0,0,78.86,89.06,19.07,19.07,0,0,0,81.13,127h179.8a27.8,27.8,0,0,0-.1-55.6h-.66a36.09,36.09,0,0,0-30.74-17.1c-1.12,0-2.25,0-3.38.16A53.09,53.09,0,0,0,173.66,10Z"/><path class="cls-3" d="M59.44,230.56a11.46,11.46,0,0,1-9.54,13.15,11.58,11.58,0,0,1-13.16-8.81S15.58,136.53,15.58,116.38c0-42.09,33.73-71.79,81.22-71.79S178,74.29,178,116.38c0,20.15-21.17,118.52-21.17,118.52a11.58,11.58,0,0,1-13.15,8.81,11.46,11.46,0,0,1-9.55-13.15"/><path class="cls-4" d="M151.64,202.37l-5.77,32A11.57,11.57,0,0,1,123,231"/><path class="cls-2" d="M152.86,202.59c-.4,2.81-.84,5.61-1.27,8.42l-1.34,8.4c-.44,2.8-.93,5.59-1.39,8.39l-.7,4.19-.35,2.1c-.06.35-.11.69-.21,1.11a10.07,10.07,0,0,1-.31,1.2,13.42,13.42,0,0,1-10.68,9.23,13.51,13.51,0,0,1-13.08-5.41,13.29,13.29,0,0,1-2.38-9.4,1.86,1.86,0,0,1,3.7.43h0a9.7,9.7,0,0,0,7.63,10.43,9.9,9.9,0,0,0,6.85-1.05,9.5,9.5,0,0,0,4.39-5.37c.33-1,.56-2.56.84-3.92l.81-4.18c.54-2.78,1.06-5.57,1.62-8.35l1.68-8.34c.58-2.78,1.14-5.56,1.75-8.33a1.24,1.24,0,0,1,2.44.44Z"/><ellipse class="cls-5" cx="69.31" cy="108.95" rx="36.24" ry="35.9"/><path class="cls-6" d="M76.8,85.43c-6.24,1.24-7.49,14.86-3.74,18.57,2.46,2.44,7.49,3.25,7.49,5s-5,2.51-7.49,5c-3.75,3.72-2.5,17.33,3.74,18.57C84.26,134,95.55,125,95.55,109S84.26,84,76.8,85.43Z"/><path class="cls-7" d="M51.81,157.22c1.25,3.72,5,9.91,10,8.67,2.42-.6,3.75-3.71,3.75-8.67"/><path class="cls-5" d="M84.3,154.75c1.25,4.95,2.5,8.66,6.25,8.66s8.75-4.95,7.5-13.61"/><path class="cls-2" d="M44.54,154.45a97.45,97.45,0,0,0,35.9-1.58,96.56,96.56,0,0,0,32.8-14.52,1.87,1.87,0,0,1,2.12,3.08h0a100.34,100.34,0,0,1-71.25,16.08,1.55,1.55,0,0,1,.45-3.07Z"/><path class="cls-2" d="M116,144.26a7.83,7.83,0,0,0-2.53-4.35,7.6,7.6,0,0,0-2.11-1.31A7.82,7.82,0,0,0,109,138a1.87,1.87,0,0,1,.31-3.72l.19,0h0a11.62,11.62,0,0,1,3.36,1.2,10.84,10.84,0,0,1,5.59,8.38,1.25,1.25,0,0,1-2.46.37Z"/><path class="cls-4" d="M70.59,231a11.56,11.56,0,0,1-22.86,3.38l-5.78-32"/><path class="cls-2" d="M72.44,230.81a13.22,13.22,0,0,1-2.37,9.4,13.51,13.51,0,0,1-8.14,5.3,13.46,13.46,0,0,1-15.62-9.11,10.11,10.11,0,0,1-.32-1.2c-.1-.42-.15-.76-.21-1.11L45.43,232l-.7-4.2c-.46-2.8-.94-5.59-1.39-8.39L42,211c-.42-2.81-.87-5.61-1.27-8.42a1.23,1.23,0,0,1,1.05-1.4,1.25,1.25,0,0,1,1.4,1c.6,2.77,1.16,5.55,1.74,8.33l1.68,8.34c.56,2.78,1.08,5.57,1.62,8.35l.81,4.17c.28,1.37.51,2.89.85,3.92a9.55,9.55,0,0,0,4.4,5.37,9.71,9.71,0,0,0,6.84,1.06,9.68,9.68,0,0,0,7.62-10.43h0a1.86,1.86,0,0,1,3.7-.44Z"/><path class="cls-4" d="M87.28,231.78a11.56,11.56,0,0,1-23,1.9l-3.14-27.6"/><path class="cls-2" d="M89.14,231.68a13.06,13.06,0,0,1-.5,4.56,13.45,13.45,0,0,1-26.26-2.45L62,229.86,61.22,222l-.7-7.87c-.23-2.63-.45-5.26-.64-7.89a1.24,1.24,0,0,1,2.47-.28c.4,2.6.77,5.22,1.15,7.83l1.07,7.83,1,7.85.51,3.92a9.54,9.54,0,0,0,.93,3.16,9.74,9.74,0,0,0,4.66,4.5,9.9,9.9,0,0,0,6.44.58A9.74,9.74,0,0,0,83.49,238a9.56,9.56,0,0,0,1.93-6.16v0a1.86,1.86,0,0,1,3.72-.17Z"/><path class="cls-4" d="M133,201.58l-3.64,32.1a11.57,11.57,0,0,1-23-1.9"/><path class="cls-2" d="M134.23,201.72c-.22,2.81-.48,5.63-.72,8.44l-.78,8.44-.84,8.43-.42,4.22-.22,2.11-.05.52-.09.61a10,10,0,0,1-.25,1.21,13.29,13.29,0,0,1-5.58,7.87,13.35,13.35,0,0,1-9.44,2.07,13.43,13.43,0,0,1-8.42-4.77,13.22,13.22,0,0,1-3-9.19,1.86,1.86,0,0,1,3.72.19h0a9.71,9.71,0,0,0,8.25,9.9,9.84,9.84,0,0,0,6.75-1.43,9.52,9.52,0,0,0,4.06-5.58,5.19,5.19,0,0,0,.19-.87l.07-.44.07-.52.27-2.1.53-4.21,1.07-8.4,1.13-8.4c.4-2.8.77-5.6,1.19-8.39a1.25,1.25,0,0,1,2.48.28Z"/><path class="cls-4" d="M109.29,200.55l-.94,32.18a11.56,11.56,0,0,1-23.11,0l-.94-32.18"/><path class="cls-2" d="M110.54,200.58q0,6.25-.05,12.49l-.06,6.24-.1,6.24-.1,6.25c0,.52,0,1-.06,1.65a12.37,12.37,0,0,1-.25,1.8,13.17,13.17,0,0,1-1.24,3.41,13.69,13.69,0,0,1-1,1.55,15.53,15.53,0,0,1-1.16,1.39,12.94,12.94,0,0,1-2.83,2.28,14.35,14.35,0,0,1-3.34,1.44,15.59,15.59,0,0,1-1.78.36c-.3,0-.61.08-.91.1l-.91,0a5.58,5.58,0,0,1-.91,0c-.3,0-.6,0-.9-.08a13.56,13.56,0,0,1-1.79-.38,13.15,13.15,0,0,1-3.34-1.43,13.4,13.4,0,0,1-4.94-5.22,13.82,13.82,0,0,1-1.25-3.41,16.6,16.6,0,0,1-.31-3.45l-.11-6.24-.1-6.25-.05-6.24q-.07-6.24,0-12.49a1.24,1.24,0,0,1,2.48-.07q.39,6.24.69,12.47l.31,6.23.26,6.24.26,6.24c0,.51,0,1.06.09,1.46a9.21,9.21,0,0,0,.2,1.28,9.67,9.67,0,0,0,4.51,6.11,9.92,9.92,0,0,0,3.65,1.26c.21,0,.43,0,.64.06a4.71,4.71,0,0,0,.65,0,9.69,9.69,0,0,0,8.53-5,9.09,9.09,0,0,0,.92-2.42,9.35,9.35,0,0,0,.2-1.29c0-.39.07-.94.09-1.46l.26-6.24.26-6.24.31-6.23q.28-6.24.68-12.47a1.24,1.24,0,0,1,1.32-1.17A1.26,1.26,0,0,1,110.54,200.58Z"/><path class="cls-1" d="M82.56,244.44H82.3A25.67,25.67,0,1,1,97.38,198a32.47,32.47,0,0,1,48-23.68,65.58,65.58,0,0,1,119-36.56,38.9,38.9,0,0,1,54.49,25.49,41.4,41.4,0,0,1-11.24,81.2h-225Z"/><path class="cls-2" d="M210.92,112.22a63.55,63.55,0,0,1,52.75,28.07,36.93,36.93,0,0,1,53.48,24.55,39.42,39.42,0,0,1-9.75,77.62H82.56v0H82.3A23.7,23.7,0,1,1,99,202,30.48,30.48,0,0,1,147.38,178c0-.71-.06-1.42-.06-2.13a63.6,63.6,0,0,1,63.6-63.6m0-4a67.55,67.55,0,0,0-67.4,62.91A34.46,34.46,0,0,0,96,194.73,27.65,27.65,0,1,0,82.3,246.41H307.63a43.38,43.38,0,0,0,12.79-84.75A40.88,40.88,0,0,0,265,135.29a67.51,67.51,0,0,0-54-27Z"/><path class="cls-8" d="M137.94,190.24c4.47-8.25,14.44-13.75,25.44-12.38"/><path class="cls-8" d="M236.78,145.33c12.08-3.17,26.49,1.5,35.17,13.43"/><path class="cls-8" d="M197.27,63.41c9.56-2.51,21,1.19,27.84,10.63"/></svg>
diff --git a/docs/_static/img/mascots/scylla-computer-headset.png b/docs/_static/img/mascots/scylla-computer-headset.png
--- a/docs/_static/img/mascots/scylla-computer-headset.png
+++ b/docs/_static/img/mascots/scylla-computer-headset.png
null
diff --git a/docs/_static/img/mascots/scylla-hardhat.png b/docs/_static/img/mascots/scylla-hardhat.png
--- a/docs/_static/img/mascots/scylla-hardhat.png
+++ b/docs/_static/img/mascots/scylla-hardhat.png
null
diff --git a/docs/_static/img/mascots/scylla-opensource.svg b/docs/_static/img/mascots/scylla-opensource.svg
--- a/docs/_static/img/mascots/scylla-opensource.svg
+++ b/docs/_static/img/mascots/scylla-opensource.svg
@@ -0,0 +1 @@
+<svg id="Calque_1" data-name="Calque 1" xmlns="http://www.w3.org/2000/svg" viewBox="16.52 39.95 169.48 207.72"><defs><style>.cls-1,.cls-2{fill:#57d1e5;}.cls-1,.cls-4,.cls-5{stroke:#3b2d55;stroke-linecap:round;stroke-linejoin:round;}.cls-1,.cls-4{stroke-width:3.7px;}.cls-3{fill:#3b2d55;}.cls-4,.cls-5{fill:#fff;}.cls-5{stroke-width:3.09px;}</style></defs><title>Plan de travail 1</title><path class="cls-1" d="M64.34,230a11.43,11.43,0,0,1-22.43,4.33S21,136.16,21,116.06c0-42,33.34-71.62,80.26-71.62s80.26,29.64,80.26,71.62c0,20.1-20.91,118.24-20.91,118.24A11.43,11.43,0,0,1,138.18,230"/><path class="cls-2" d="M155.46,201.85l-5.71,32a11.43,11.43,0,0,1-22.59-3.38"/><path class="cls-3" d="M156.67,202.06l-1.25,8.38-1.32,8.36-1.37,8.35-.69,4.17a41.44,41.44,0,0,1-.84,4.37,13.27,13.27,0,0,1-25.88-5.46,1.85,1.85,0,0,1,3.68.43,9.55,9.55,0,0,0,1.8,6.67,9.4,9.4,0,0,0,5.75,3.75,9.62,9.62,0,0,0,6.78-1.08,9.47,9.47,0,0,0,4.31-5.39c.31-1,.55-2.57.82-3.92l.8-4.16,1.61-8.31,1.65-8.3,1.72-8.29a1.23,1.23,0,0,1,2.43.43Z"/><circle class="cls-4" cx="74.1" cy="108.65" r="35.81"/><path class="cls-3" d="M81.5,85.19c-6.17,1.24-7.4,14.82-3.7,18.52,2.43,2.44,7.41,3.25,7.41,4.94s-5,2.51-7.41,4.94c-3.7,3.7-2.47,17.29,3.7,18.52,7.37,1.48,18.53-7.41,18.53-23.46S88.87,83.72,81.5,85.19Z"/><path class="cls-5" d="M56.81,156.81c1.23,3.7,4.94,9.88,9.88,8.64,2.39-.6,3.7-3.7,3.7-8.64"/><path class="cls-4" d="M88.91,154.34c1.24,4.94,2.47,8.64,6.18,8.64s8.64-4.94,7.41-13.58"/><path class="cls-3" d="M49.63,154.05A95.15,95.15,0,0,0,117.5,138a1.85,1.85,0,1,1,2.11,3h0a98.51,98.51,0,0,1-70.43,16,1.54,1.54,0,0,1,.46-3Z"/><path class="cls-3" d="M120.27,143.87a7.93,7.93,0,0,0-2.49-4.34,7.65,7.65,0,0,0-4.43-1.88,1.86,1.86,0,0,1,.28-3.7l.19,0h.05a11,11,0,0,1,6.09,3.37,10.58,10.58,0,0,1,2.75,6.18,1.22,1.22,0,0,1-1.11,1.34,1.24,1.24,0,0,1-1.33-1Z"/><path class="cls-2" d="M75.37,230.44a11.43,11.43,0,0,1-22.6,3.38l-5.7-32"/><path class="cls-3" d="M77.2,230.22a13.26,13.26,0,0,1-10.41,14.66,13.14,13.14,0,0,1-9.53-1.6,13.34,13.34,0,0,1-5.93-7.58,40.11,40.11,0,0,1-.85-4.37l-.69-4.18-1.37-8.35-1.32-8.36-1.25-8.38a1.23,1.23,0,0,1,2.43-.43L50,209.92l1.66,8.3,1.6,8.31.8,4.15c.27,1.36.51,2.89.82,3.92a9.58,9.58,0,0,0,18.65-3.93h0a1.85,1.85,0,0,1,3.67-.44Z"/><path class="cls-2" d="M91.86,231.18a11.42,11.42,0,0,1-22.76,1.9l-3.6-32"/><path class="cls-3" d="M93.71,231.08A13.27,13.27,0,0,1,82.43,245a13.16,13.16,0,0,1-9.38-2.15A13.33,13.33,0,0,1,67.57,235a34.51,34.51,0,0,1-.58-4.42l-.42-4.19-.83-8.4L65,209.6l-.7-8.41a1.23,1.23,0,0,1,2.45-.28l1.18,8.36L69,217.62,70.07,226l.53,4.18c.19,1.38.31,2.88.58,3.93A9.57,9.57,0,0,0,90,231.28h0a1.85,1.85,0,0,1,3.7-.19Z"/><path class="cls-2" d="M137,201.05l-3.6,32a11.43,11.43,0,0,1-22.77-1.9"/><path class="cls-3" d="M138.26,201.19l-.71,8.41-.77,8.39-.83,8.39-.41,4.2A38.06,38.06,0,0,1,135,235a13.27,13.27,0,0,1-23.22,5.24,13.42,13.42,0,0,1-2.93-9.15,1.86,1.86,0,0,1,2-1.73,1.84,1.84,0,0,1,1.73,1.93,9.6,9.6,0,0,0,2.22,6.52,9.49,9.49,0,0,0,5.94,3.38,9.68,9.68,0,0,0,6.69-1.47,9.43,9.43,0,0,0,4-5.61c.26-1,.39-2.55.57-3.93l.53-4.18,1.06-8.36,1.11-8.36,1.18-8.36a1.24,1.24,0,0,1,2.46.28Z"/><path class="cls-2" d="M113.61,200l-.93,32.1a11.42,11.42,0,0,1-22.84,0L88.91,200"/><path class="cls-3" d="M114.84,200.06q0,12.44-.19,24.87l-.1,6.22a17.8,17.8,0,0,1-.3,3.42,13.31,13.31,0,0,1-13,10.59,12.81,12.81,0,0,1-3.59-.5,12.62,12.62,0,0,1-3.32-1.46A13.38,13.38,0,0,1,89.49,238a13.15,13.15,0,0,1-1.22-3.4,17,17,0,0,1-.3-3.42l-.1-6.22q-.23-12.44-.19-24.87a1.24,1.24,0,0,1,2.47-.07c.49,8.28.92,16.56,1.24,24.84l.26,6.21a15.61,15.61,0,0,0,.27,2.75,9.55,9.55,0,0,0,9.35,7.48,9.49,9.49,0,0,0,8.44-5.05,9,9,0,0,0,.9-2.42,15.73,15.73,0,0,0,.27-2.76l.26-6.21c.32-8.28.75-16.56,1.23-24.84a1.24,1.24,0,0,1,2.47.07Z"/></svg>
diff --git a/docs/_utils/redirections.yaml b/docs/_utils/redirections.yaml
--- a/docs/_utils/redirections.yaml
+++ b/docs/_utils/redirections.yaml
@@ -0,0 +1,486 @@
+### a dictionary of redirections
+#old path: new path
+
+# removing redirection html script files
+cassandra-compatibility: /using-scylla/cassandra-compatibility
+getting-started/security: /operating-scylla/authorization
+getting-started/rbac_usecase: /operating-scylla/security/rbac-usecase
+operating-scylla/auditing: /operating-scylla/security/auditing
+operating-scylla/configure_ssl_on_live_scylla_cluster: /operating-scylla/security
+using-scylla/migrate: /procedures/cassandra_to_scylla_migration_process
+troubleshooting/performance_problem: /troubleshooting/report-scylla-problem
+
+#
+nodetool: /operating-scylla/nodetool
+procedures: /operating-scylla/procedures
+procedures/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+procedures/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+procedures/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+procedures/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+procedures/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+procedures/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+procedures/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+procedures/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+procedures/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+procedures/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+procedures/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+procedures/backup: /operating-scylla/procedures/backup-restore/backup
+procedures/restore: /operating-scylla/procedures/backup-restore/restore
+procedures/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+procedures/repair: /operating-scylla/procedures/maintenance/repair
+procedures/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+procedures/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+procedures/cassandra_to_scylla_migration_process: /operating-scylla/procedures/cassandra-to-scylla-migration-process
+procedures/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+admin: /operating-scylla/admin
+third-parties: /using-scylla/integrations
+system-configuration: /getting-started/system-configuration
+tls-ssl: /operating-scylla/security
+/operating-scylla/manager/manager-setup: /operating-scylla/manager
+/operating-scylla/manager/manager-cluster: /operating-scylla/manager
+/operating-scylla/manager/manager-overview: /operating-scylla/manager
+/operating-scylla/manager/manager-remote-datastore: /operating-scylla/manager
+/operating-scylla/manager/sctool: /operating-scylla/manager
+/operating-scylla/manager/1.2/manager-index: /operating-scylla/manager
+/operating-scylla/manager/2.0/restore: /operating-scylla/manager/2.0/restore-a-backup
+/operating-scylla/manager/2.0/overview: /operating-scylla/manager/2.0/architecture
+/operating-scylla/snitch: /operating-scylla/system-configuration/snitch
+/operating-scylla/troubleshooting/report_scylla_problem: /troubleshooting/report-scylla-problem
+/operating-scylla/procedures/backup: /operating-scylla/procedures/backup-restore/backup
+/operating-scylla/procedures/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+/operating-scylla/procedures/restore: /operating-scylla/procedures/backup-restore/restore
+/operating-scylla/procedures/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+/operating-scylla/procedures/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+/operating-scylla/procedures/clear_data: /operating-scylla/procedures/cluster-management/clear-data
+/operating-scylla/procedures/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+/operating-scylla/procedures/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+/operating-scylla/procedures/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+/operating-scylla/procedures/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+/operating-scylla/procedures/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+/operating-scylla/procedures/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+/operating-scylla/procedures/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+/operating-scylla/procedures/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+/operating-scylla/procedures/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+/operating-scylla/procedures/revoke_decommission: /operating-scylla/procedures/cluster-management/revoke-decommission
+/operating-scylla/procedures/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+/operating-scylla/procedures/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+/operating-scylla/procedures/repair: /operating-scylla/procedures/maintenance/repair
+/operating-scylla/procedures/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+
+# sstable2
+
+/architecture/sstable/sstable-summary-file: /architecture/sstable/sstable2/sstable-summary-file
+/architecture/sstable/sstable-compression: /architecture/sstable/sstable2/sstable-compression
+/architecture/sstable/sstable-format: /architecture/sstable/sstable2/sstable_format
+/architecture/sstable/sstable-interpretation: /architecture/sstable/sstable2/sstable-interpretation
+/architecture/sstable/sstable-data-file: /architecture/sstable/sstable2/sstable-data-file
+
+# upgrade 2017 - 2018
+/upgrade/upgrade-guide-from-2017.1-to-2018.1: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1
+/upgrade/metric-update-2017.1-to-2018.1: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/metric-update-2017.1-to-2018.1
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-debian
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-rpm
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-ubuntu
+
+# upgrade 2017 - 2017
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-debian
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-rpm
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-ubuntu
+
+# upgrade 2018 - 2018
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-rpm
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-ubuntu
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-debian
+
+# upgrade manager
+/upgrade/upgrade-guide-from-manager: /upgrade/upgrade-manager/upgrade-guide-from-manager
+/upgrade/upgrade-guide-from-manager-1.0.x-to-1.1.x: /upgrade/upgrade-manager/upgrade-guide-from-manager-1.0.x-to-1.1.x
+/upgrade/upgrade-guide-from-manager-1.1.x-to-1.2.x: /upgrade/upgrade-manager/upgrade-guide-from-manager-1.1.x-to-1.2.x
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-from-2.0.0-to-2.0.1: /upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-from-2.x.y-to-2.x.z
+
+# upgrade monitoring
+/upgrade/upgrade-guide-from-monitoring: /upgrade/upgrade-monitor/upgrade-guide-from-monitoring
+/upgrade/upgrade-guide-from-monitoring-1.x-to-monitoring-2.x: /upgrade/upgrade-monitor/upgrade-guide-from-monitoring-1.x-to-monitoring-2.x
+
+# upgrade OpenSource
+# upgrade 1.0 to 1.1
+/upgrade/upgrade-guide-from-1.0-to-1.1: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1
+/upgrade/upgrade-guide-from-1.0-to-1.1-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1/upgrade-guide-from-1.0-to-1.1-rpm
+/upgrade/upgrade-guide-from-1.0-to-1.1-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1/upgrade-guide-from-1.0-to-1.1-ubuntu
+
+# upgrade 1.1 to 1.2
+/upgrade/upgrade-guide-from-1.1-to-1.2: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2
+/upgrade/upgrade-guide-from-1.1-to-1.2-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2/upgrade-guide-from-1.1-to-1.2-rpm
+/upgrade/upgrade-guide-from-1.1-to-1.2-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2/upgrade-guide-from-1.1-to-1.2-ubuntu
+
+# upgrade 1.2 to 1.3
+/upgrade/upgrade-guide-from-1.2-to-1.3: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3
+/upgrade/upgrade-guide-from-1.2-to-1.3-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3/upgrade-guide-from-1.2-to-1.3-rpm
+/upgrade/upgrade-guide-from-1.2-to-1.3-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3/upgrade-guide-from-1.2-to-1.3-ubuntu
+
+# upgrade 1.3 to 1.4
+
+/upgrade/upgrade-guide-from-1.3-to-1.4: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4
+/upgrade/upgrade-guide-from-1.3-to-1.4-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4/upgrade-guide-from-1.3-to-1.4-rpm
+/upgrade/upgrade-guide-from-1.3-to-1.4-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4/upgrade-guide-from-1.3-to-1.4-ubuntu
+
+# upgrade 1.4 to 1.5
+/upgrade/upgrade-guide-from-1.4-to-1.5: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5
+/upgrade/upgrade-guide-from-1.4-to-1.5-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5/upgrade-guide-from-1.4-to-1.5-rpm
+/upgrade/upgrade-guide-from-1.4-to-1.5-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5/upgrade-guide-from-1.4-to-1.5-ubuntu
+
+# upgrade 1.5 to 1.6
+/upgrade/upgrade-guide-from-1.5-to-1.6: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6
+/upgrade/upgrade-guide-from-1.5-to-1.6-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6/upgrade-guide-from-1.5-to-1.6-rpm
+/upgrade/upgrade-guide-from-1.5-to-1.6-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6/upgrade-guide-from-1.5-to-1.6-ubuntu
+
+# upgrade 1.6 to 1.7
+/upgrade/upgrade-guide-from-1.6-to-1.7: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7
+/upgrade/upgrade-guide-from-1.6-to-1.7-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-rpm
+/upgrade/upgrade-guide-from-1.6-to-1.7-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-ubuntu
+/upgrade/upgrade-guide-from-1.6-to-1.7-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-debian
+
+# upgrade 1.7 to 2.0
+/upgrade/upgrade-guide-from-1.7-to-2.0: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0
+/upgrade/upgrade-guide-from-1.7-to-2.0-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-rpm
+/upgrade/upgrade-guide-from-1.7-to-2.0-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-ubuntu
+/upgrade/upgrade-guide-from-1.7-to-2.0-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-debian
+/upgrade/metric-update-1.7-to-2.0: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/metric-update-1.7-to-2.0
+
+
+# upgrade 1.x.y-to-1.x.z
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-rpm
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-ubuntu
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-debian
+
+# upgrade 2.0 to 2.1
+/upgrade/upgrade-guide-from-2.0-to-2.1: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1
+/upgrade/upgrade-guide-from-2.0-to-2.1-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-rpm
+/upgrade/upgrade-guide-from-2.0-to-2.1-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-ubuntu
+/upgrade/upgrade-guide-from-2.0-to-2.1-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-debian
+/upgrade/metric-update-2.0-to-2.1: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/metric-update-2.0-to-2.1
+
+# upgrade 2.1 to 2.2
+/upgrade/upgrade-guide-from-2.1-to-2.2: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2
+/upgrade/upgrade-guide-from-2.1-to-2.2-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-rpm
+/upgrade/upgrade-guide-from-2.1-to-2.2-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-ubuntu
+/upgrade/upgrade-guide-from-2.1-to-2.2-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-debian
+/upgrade/metric-update-2.1-to-2.2: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/metric-update-2.1-to-2.2
+
+# upgrade 2.2 to 2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-rpm
+/upgrade/upgrade-guide-from-2.2-to-2.3-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-ubuntu
+/upgrade/upgrade-guide-from-2.2-to-2.3-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-debian
+/upgrade/metric-update-2.2-to-2.3: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/metric-update-2.2-to-2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3-ubuntu-16-04: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-ubuntu-16-04
+
+# upgrade 2.x.y to 2.x.z
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-debian
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-rpm
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-ubuntu
+
+# Upgrade OS to Enterprise
+/upgrade/upgrade-guide-from-1.6-to-2017.1: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1
+/upgrade/upgrade-guide-from-1.6-to-2017.1-debian: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-debian
+/upgrade/upgrade-guide-from-1.6-to-2017.1-rpm: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-rpm
+/upgrade/upgrade-guide-from-1.6-to-2017.1-ubuntu: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-ubuntu
+
+/upgrade/upgrade-guide-from-2.0-to-2018.1: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1
+/upgrade/upgrade-guide-from-2.0-to-2018.1-debian: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2087.1/upgrade-guide-from-2.0-to-2018.1-debian
+/upgrade/upgrade-guide-from-2.0-to-2018.1-rpm: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1/upgrade-guide-from-2.0-to-2018.1-rpm
+/upgrade/upgrade-guide-from-2.0-to-2018.1-ubuntu: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1/upgrade-guide-from-2.0-to-2018.1-ubuntu
+
+/operating-scylla/upgrade: /upgrade
+/rst_include/upgrade-index: /upgrade
+
+#removed page - how to kb
+/kb/kb-howto: /kb
+
+# monitoring
+/operating-scylla/monitoring/Scylla_Monitoring_Cheatsheet.pdf: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitor_troubleshoot: /operating-scylla/monitoring
+/operating-scylla/monitoring/min-prod-hw: /operating-scylla/monitoring
+/operating-scylla/monitoring/cql_optimization: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitoring_apis: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitor_without_docker.2.1: /operating-scylla/monitoring
+/operating-scylla/monitoring/updating_dashboard: /operating-scylla/monitoring
+/operating-scylla/monitoring/_common/monitor-back-index: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitoring_stack: /operating-scylla/monitoring
+
+#scylla-learn
+/using-scylla/learn-example: /using-scylla/learn
+
+# scylla-matrix
+/getting-started/support-matrix: /getting-started
+
+# operators
+/getting-started/cql/operators: /getting-started/cql
+
+# move kb for Kafka connector to Integrations
+/kb/kafka-connector: /using-scylla/integrations/kafka-connector
+/kb/sink-config: /using-scylla/integrations/sink-config
+
+# rename repair file in manager issue #2387
+/operating-scylla/manager/2.0/repair-a-cluster: /operating-scylla/manager
+
+# https://github.com/scylladb/scylla-docs/issues/2412
+/operating-scylla/runtime-authentication: /operating-scylla/security/runtime-authentication
+
+# https://github.com/scylladb/scylla-doc-issues/issues/298
+/kb/os-support: /getting-started/os-support
+
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z: /upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-2.x.y-to-2.x.z: /upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-2.x.a-to-2.y.b
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-row-level-repair: /upgrade/upgrade-manager/upgrade-2.x.a-to-2.y.b/upgrade-row-level-repair
+
+# scylla-cloud rename BYOA
+/scylla-cloud/cloud-setup/xaws-account: /scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa
+
+# scylla Monitor
+/operating-scylla/monitoring/matrix: https://monitoring.docs.scylladb.com/stable/reference/matrix.html
+
+#scylla operator
+/operating-scylla/scylla-operator/generic: https://scylladb.github.io/scylla-operator/master/generic
+/operating-scylla/scylla-operator/eks: https://scylladb.github.io/scylla-operator/master/eks
+/operating-scylla/scylla-operator/gke: https://scylladb.github.io/scylla-operator/master/gke
+/operating-scylla/scylla-operator/manager: https://scylladb.github.io/scylla-operator/master/manager
+/operating-scylla/scylla-operator/scylla_cluster_crd: https://scylladb.github.io/scylla-operator/master/scylla_cluster_crd
+/operating-scylla/scylla-operator/contributing: https://scylladb.github.io/scylla-operator/master/contributing
+
+#scylla-manager
+/operating-scylla/manager/2.2: https://manager.docs.scylladb.com/branch-2.2/index.html
+/operating-scylla/manager/2.2/backup: https://manager.docs.scylladb.com/branch-2.2/backup
+/operating-scylla/manager/2.2/backup/backup-examples: https://manager.docs.scylladb.com/branch-2.2/backup/examples
+/operating-scylla/manager/2.2/backup/get-schema: https://manager.docs.scylladb.com/branch-2.2/backup
+/operating-scylla/manager/2.2/backup/grant-access-S3: https://manager.docs.scylladb.com/branch-2.2/backup/setup-aws-s3
+/operating-scylla/manager/2.2/backup/grant-access-gcs: https://manager.docs.scylladb.com/branch-2.2/backup/setup-gcs
+/operating-scylla/manager/2.2/cluster-health-check: https://manager.docs.scylladb.com/branch-2.2/health-check.rst
+/operating-scylla/manager/2.2/config/index: https://manager.docs.scylladb.com/branch-2.2/config/index
+/operating-scylla/manager/2.2/config/scylla-manager-agent-config: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-agent-config
+/operating-scylla/manager/2.2/config/scylla-manager-agent: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-agent-config
+/operating-scylla/manager/2.2/config/scylla-manager-config: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-config
+/operating-scylla/manager/2.2/config/scylla-manager: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-config
+/operating-scylla/manager/2.2/index: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/introduction-to-scylla-manager: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/manage-nodes/add-a-cluster: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/add-node: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/connect-cluster-to-monitor: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/index: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/manage-nodes/remove-node: https://manager.docs.scylladb.com/branch-2.2/troubleshooting
+/operating-scylla/manager/2.2/sctool/backup: https://manager.docs.scylladb.com/branch-2.2/sctool/backup
+/operating-scylla/manager/2.2/sctool/cluster: https://manager.docs.scylladb.com/branch-2.2/sctool/cluster
+/operating-scylla/manager/2.2/sctool/global-flags-and-variables: https://manager.docs.scylladb.com/branch-2.2/sctool/global-flags-and-variables
+/operating-scylla/manager/2.2/sctool/index: https://manager.docs.scylladb.com/branch-2.2/sctool/index
+/operating-scylla/manager/2.2/sctool/repair: https://manager.docs.scylladb.com/branch-2.2/repair/index
+/operating-scylla/manager/2.2/sctool/status: https://manager.docs.scylladb.com/branch-2.2/status
+/operating-scylla/manager/2.2/sctool/task: https://manager.docs.scylladb.com/branch-2.2/sctool/task
+/operating-scylla/manager/2.2/sctool/version: https://manager.docs.scylladb.com/branch-2.2/sctool/version
+/operating-scylla/manager/2.2/scylla-manager-agent-installation: https://manager.docs.scylladb.com/branch-2.2/install-scylla-manager-agent
+/operating-scylla/manager/2.2/scylla-manager-installation: https://manager.docs.scylladb.com/branch-2.2/install-scylla-manager
+/operating-scylla/manager/2.2/scylla-monitoring-integration: https://manager.docs.scylladb.com/branch-2.2/scylla-monitoring
+/operating-scylla/manager/2.2/backup/prepare-nodes: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/backup/index: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/backup/restore-a-backup: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/repair-a-cluster: https://manager.docs.scylladb.com/branch-2.2/repair/index
+
+# Remove Scylla Alternator and move to OSS docs site
+
+/using-scylla/alternator/alternator: https://scylladb.github.io/scylla/stable/alternator/alternator
+/using-scylla/alternator/getting-started: https://scylladb.github.io/scylla/stable/alternator/getting-started
+
+# Create Drivers directory and move files to it
+/getting-started/scylla_drivers: /using-scylla/drivers/cql-drivers/index
+/using-scylla/drivers-intro: /using-scylla/drivers/cql-drivers/index
+/using-scylla/scylla-cpp-driver: /using-scylla/drivers/cql-drivers/scylla-cpp-driver
+/using-scylla/scylla-go-driver: /using-scylla/drivers/cql-drivers/scylla-go-driver
+/using-scylla/scylla-gocqlx-driver: /using-scylla/drivers/cql-drivers/scylla-gocqlx-driver
+/using-scylla/scylla-java-driver: /using-scylla/drivers/cql-drivers/scylla-java-driver
+/using-scylla/scylla-python-driver: /using-scylla/drivers/cql-drivers/scylla-python-driver
+/using-scylla/scylla_drivers: /using-scylla/drivers
+
+# change vpc peering to AWS vpc peering
+/scylla-cloud/cloud-setup/vpc-peering: /scylla-cloud/cloud-setup/AWS/aws-vpc-peering
+
+#remove social reader KB
+/kb/social-reader: /kb/index
+
+# move scylla cloud for AWS to dedicated directory
+/scylla-cloud/cloud-setup/aws-vpc-peering: /scylla-cloud/cloud-setup/AWS/aws-vpc-peering
+/scylla-cloud/cloud-setup/cloud-prom-proxy: /scylla-cloud/cloud-setup/AWS/cloud-prom-proxy
+/scylla-cloud/cloud-setup/outposts: /scylla-cloud/cloud-setup/AWS/outposts
+/scylla-cloud/cloud-setup/scylla-cloud-byoa: /scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa
+
+# Scylla Cloud
+/scylla-cloud/cloud-setup/gcp-vpc-peering: /scylla-cloud/cloud-setup/GCP/gcp-vpc-peering
+/scylla-cloud/cloud-setup/GCP/gcp-vcp-peering: /scylla-cloud/cloud-setup/GCP/gcp-vpc-peering
+
+# replace underscore with dash for install_scylla
+/getting-started/install_scylla/air-gapped-install: /getting-started/install-scylla/air-gapped-install
+/getting-started/install_scylla/config-commands: /getting-started/install-scylla/config-commands
+/getting-started/install_scylla/dev_mod: /getting-started/install-scylla/dev-mod
+/getting-started/install_scylla/disable_housekeeping: /getting-started/install-scylla/disable-housekeeping
+/getting-started/install_scylla/index: /getting-started/install-scylla/index
+/getting-started/install_scylla/rpm_info: /getting-started/install-scylla/rpm-info
+/getting-started/install_scylla/unified-installer: /getting-started/install-scylla/unified-installer
+
+# replace underscore with dash for error_messages
+/troubleshooting/error_messages/address_already_in_use: /troubleshooting/error-messages/address-already-in-use
+/troubleshooting/error_messages/create_mv: /troubleshooting/error-messages/create-mv
+/troubleshooting/error_messages/index: /troubleshooting/error-messages/index
+/troubleshooting/error_messages/invalid-ssl-prot-error: /troubleshooting/error-messages/invalid-ssl-prot-error
+/troubleshooting/error_messages/kb_fs_not_qualified_aio: /troubleshooting/error-messages/kb-fs-not-qualified-aio
+/troubleshooting/error_messages/schema_mismatch: /troubleshooting/error-messages/schema-mismatch
+
+
+# replace underscore with dash for files names
+/troubleshooting/large_rows_large_cells_tables: /troubleshooting/large-rows-large-cells-tables
+/troubleshooting/pointless_compactions: /troubleshooting/pointless-compactions
+/troubleshooting/debugging_large_partition: /troubleshooting/debugging-large-partition
+/troubleshooting/large_partition_table: /troubleshooting/large-partition-table
+/troubleshooting/copy_from_failed: /troubleshooting/copy-from-failed
+/troubleshooting/password_reset: /troubleshooting/password-reset
+/troubleshooting/reverse_dns_sshd: /troubleshooting/reverse-dns-sshd
+/troubleshooting/failed_decommission: /troubleshooting/failed-decommission
+/troubleshooting/drop_table_space_up: /troubleshooting/drop-table-space-up
+/troubleshooting/error-messages/create_mv: /troubleshooting/error-messages/create-mv
+/troubleshooting/error-messages/kb_fs_not_qualified_aio: /troubleshooting/error-messages/kb-fs-not-qualified-aio
+/troubleshooting/error-messages/address_already_in_use: /troubleshooting/error-messages/address-already-in-use
+/troubleshooting/error-messages/schema_mismatch: /troubleshooting/error-messages/schema-mismatch
+/troubleshooting/scylla_wont_start: /troubleshooting/scylla-wont-start
+/troubleshooting/change_ownership: /troubleshooting/change-ownership
+/troubleshooting/space_up: /troubleshooting/space-up
+/troubleshooting/report_scylla_problem: /troubleshooting/report-scylla-problem
+/troubleshooting/sstable_corruption: /troubleshooting/sstable-corruption
+/troubleshooting/log_level: /troubleshooting/log-level
+/troubleshooting/manager_monitoring_integration: /troubleshooting/manager-monitoring-integration
+/getting-started/non-reserved_keywords: /getting-started/non-reserved-keywords
+/getting-started/install-scylla/rpm_info: /getting-started/install-scylla/rpm-info
+/getting-started/install-scylla/dev_mod: /getting-started/install-scylla/dev-mod
+/getting-started/install-scylla/disable_housekeeping: /getting-started/install-scylla/disable-housekeeping
+/getting-started/time_to_live: /getting-started/time-to-live
+/getting-started/secondary_indexes: /getting-started/secondary-indexes
+/getting-started/scylla_in_a_shared_environment: /getting-started/scylla-in-a-shared-environment
+/getting-started/reserved_keywords: /getting-started/reserved-keywords
+/using-scylla/integrations/integration_kairos: /using-scylla/integrations/integration-kairos
+/upgrade/ami_upgrade: /upgrade/ami-upgrade
+/scylla-cloud/cloud-services/scylla_cloud_costs: /scylla-cloud/cloud-services/scylla-cloud-costs
+/scylla-cloud/cloud-services/scylla_cloud_managin_versions: /scylla-cloud/cloud-services/scylla-cloud-managin-versions
+/scylla-cloud/cloud-services/scylla_cloud_support_alerts_sla: /scylla-cloud/cloud-services/scylla-cloud-support-alerts-sla
+/scylla-cloud/cloud-services/scylla_cloud-autoscale-and-resizing: /scylla-cloud/cloud-services/scylla-cloud-autoscale-and-resizing
+/operating-scylla/monitoring/3.1/monitoring_stack: /operating-scylla/monitoring/3.1/monitoring-stack
+/operating-scylla/monitoring/3.1/updating_dashboard: /operating-scylla/monitoring/3.1/updating-dashboard
+/operating-scylla/monitoring/3.1/cql_optimization: /operating-scylla/monitoring/3.1/cql-optimization
+/operating-scylla/monitoring/3.1/monitoring_apis: /operating-scylla/monitoring/3.1/monitoring-apis
+/operating-scylla/monitoring/3.1/monitor_troubleshoot: /operating-scylla/monitoring/3.1/monitor-troubleshoot
+/operating-scylla/monitoring/3.1/monitor: t_docker with ./operating-scylla/monitoring/3.1/monitor-without-docker
+/operating-scylla/monitoring/2.4/monitoring_stack: /operating-scylla/monitoring/2.4/monitoring-stack
+/operating-scylla/monitoring/2.4/updating_dashboard: /operating-scylla/monitoring/2.4/updating-dashboard
+/operating-scylla/monitoring/2.4/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.4/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.4/cql_optimization: /operating-scylla/monitoring/2.4/cql-optimization
+/operating-scylla/monitoring/2.4/monitoring_apis: /operating-scylla/monitoring/2.4/monitoring-apis
+/operating-scylla/monitoring/2.4/monitor_troubleshoot: /operating-scylla/monitoring/2.4/monitor-troubleshoot
+/operating-scylla/monitoring/2.2/monitoring_stack: /operating-scylla/monitoring/2.2/monitoring-stack
+/operating-scylla/monitoring/2.2/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.2/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.2/monitoring_apis: /operating-scylla/monitoring/2.2/monitoring-apis
+/operating-scylla/monitoring/2.2/monitor_troubleshoot: /operating-scylla/monitoring/2.2/monitor-troubleshoot
+/operating-scylla/monitoring/3.4/monitoring_stack: /operating-scylla/monitoring/3.4/monitoring-stack
+/operating-scylla/monitoring/3.4/start_all: /operating-scylla/monitoring/3.4/start-all
+/operating-scylla/monitoring/3.4/updating_dashboard: /operating-scylla/monitoring/3.4/updating-dashboard
+/operating-scylla/monitoring/3.4/cql_optimization: /operating-scylla/monitoring/3.4/cql-optimization
+/operating-scylla/monitoring/3.4/monitoring_apis: /operating-scylla/monitoring/3.4/monitoring-apis
+/operating-scylla/monitoring/3.4/monitor_troubleshoot: /operating-scylla/monitoring/3.4/monitor-troubleshoot
+/operating-scylla/monitoring/3.4/monitor: t_docker with ./operating-scylla/monitoring/3.4/monitor-without-docker
+/operating-scylla/monitoring/3.3/monitoring_stack: /operating-scylla/monitoring/3.3/monitoring-stack
+/operating-scylla/monitoring/3.3/start_all: /operating-scylla/monitoring/3.3/start-all
+/operating-scylla/monitoring/3.3/updating_dashboard: /operating-scylla/monitoring/3.3/updating-dashboard
+/operating-scylla/monitoring/3.3/cql_optimization: /operating-scylla/monitoring/3.3/cql-optimization
+/operating-scylla/monitoring/3.3/monitoring_apis: /operating-scylla/monitoring/3.3/monitoring-apis
+/operating-scylla/monitoring/3.3/monitor_troubleshoot: /operating-scylla/monitoring/3.3/monitor-troubleshoot
+/operating-scylla/monitoring/3.3/monitor: t_docker with ./operating-scylla/monitoring/3.3/monitor-without-docker
+/operating-scylla/monitoring/3.2/monitoring_stack: /operating-scylla/monitoring/3.2/monitoring-stack
+/operating-scylla/monitoring/3.2/start_all: /operating-scylla/monitoring/3.2/start-all
+/operating-scylla/monitoring/3.2/updating_dashboard: /operating-scylla/monitoring/3.2/updating-dashboard
+/operating-scylla/monitoring/3.2/cql_optimization: /operating-scylla/monitoring/3.2/cql-optimization
+/operating-scylla/monitoring/3.2/monitoring_apis: /operating-scylla/monitoring/3.2/monitoring-apis
+/operating-scylla/monitoring/3.2/monitor_troubleshoot: /operating-scylla/monitoring/3.2/monitor-troubleshoot
+/operating-scylla/monitoring/3.2/monitor: t_docker with ./operating-scylla/monitoring/3.2/monitor-without-docker
+/operating-scylla/monitoring/3.0/monitoring_stack: /operating-scylla/monitoring/3.0/monitoring-stack
+/operating-scylla/monitoring/3.0/updating_dashboard: /operating-scylla/monitoring/3.0/updating-dashboard
+/operating-scylla/monitoring/3.0/cql_optimization: /operating-scylla/monitoring/3.0/cql-optimization
+/operating-scylla/monitoring/3.0/monitoring_apis: /operating-scylla/monitoring/3.0/monitoring-apis
+/operating-scylla/monitoring/3.0/monitor_troubleshoot: /operating-scylla/monitoring/3.0/monitor-troubleshoot
+/operating-scylla/monitoring/3.0/monitor: t_docker with ./operating-scylla/monitoring/3.0/monitor-without-docker
+/operating-scylla/monitoring/2.3/monitoring_stack: /operating-scylla/monitoring/2.3/monitoring-stack
+/operating-scylla/monitoring/2.3/updating_dashboard: /operating-scylla/monitoring/2.3/updating-dashboard
+/operating-scylla/monitoring/2.3/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.3/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.3/cql_optimization: /operating-scylla/monitoring/2.3/cql-optimization
+/operating-scylla/monitoring/2.3/monitoring_apis: /operating-scylla/monitoring/2.3/monitoring-apis
+/operating-scylla/monitoring/2.3/monitor_troubleshoot: /operating-scylla/monitoring/2.3/monitor-troubleshoot
+/operating-scylla/procedures/config-change/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+/operating-scylla/procedures/config-change/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+/operating-scylla/procedures/config-change/rolling_restart: /operating-scylla/procedures/config-change/rolling-restart
+/operating-scylla/procedures/cassandra_to_scylla_migration_process: /operating-scylla/procedures/cassandra-to-scylla-migration-process
+/operating-scylla/procedures/backup-restore/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+/operating-scylla/procedures/tips/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+/operating-scylla/procedures/cluster-management/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+/operating-scylla/procedures/cluster-management/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+/operating-scylla/procedures/cluster-management/clear_data: /operating-scylla/procedures/cluster-management/clear-data
+/operating-scylla/procedures/cluster-management/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+/operating-scylla/procedures/cluster-management/remove_seed: /operating-scylla/procedures/cluster-management/remove-seed
+/operating-scylla/procedures/cluster-management/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+/operating-scylla/procedures/cluster-management/membership_changes: /operating-scylla/procedures/cluster-management/membership-changes
+/operating-scylla/procedures/cluster-management/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+/operating-scylla/procedures/cluster-management/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+/operating-scylla/procedures/cluster-management/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+/operating-scylla/procedures/cluster-management/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+/operating-scylla/procedures/cluster-management/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+/operating-scylla/procedures/cluster-management/revoke_decommission: /operating-scylla/procedures/cluster-management/revoke-decommission
+/operating-scylla/procedures/cluster-management/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+/operating-scylla/procedures/cluster-management/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+/operating-scylla/security/security_checklist: /operating-scylla/security/security-checklist
+/operating-scylla/security/client_node_encryption: /operating-scylla/security/client-node-encryption
+/operating-scylla/security/generate_certificate: /operating-scylla/security/generate-certificate
+/operating-scylla/security/node_node_encryption: /operating-scylla/security/node-node-encryption
+/operating-scylla/security/rbac_usecase: /operating-scylla/security/rbac-usecase
+/architecture/console_CL_full_demo: /architecture/console-CL-full-demo
+/architecture/sstable/sstable3/sstables_3_statistics: /architecture/sstable/sstable3/sstables-3-statistics
+/architecture/sstable/sstable3/sstables_3_summary: /architecture/sstable/sstable3/sstables-3-summary
+/architecture/sstable/sstable3/sstables_3_data_file_format: /architecture/sstable/sstable3/sstables-3-data-file-format
+/architecture/sstable/sstable3/sstables_3_index: /architecture/sstable/sstable3/sstables-3-index
+/architecture/sstable/sstable3/sstable_format: /architecture/sstable/sstable3/sstable-format
+
+
+# scylla-cloud migration
+/scylla-cloud: https://cloud.docs.scylladb.com/stable/
+
+/scylla-cloud/cloud-services: https://cloud.docs.scylladb.com/stable/cloud-services
+/scylla-cloud/cloud-services/cloud-backup: https://cloud.docs.scylladb.com/stable/cloud-services/cloud-backup
+/scylla-cloud/cloud-services/scylla-cloud-autoscale-and-resizing: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-autoscale-and-resizing
+/scylla-cloud/cloud-services/scylla-cloud-costs: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-costs
+/scylla-cloud/cloud-services/scylla-cloud-deployment-locations: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-deployment-locations
+/scylla-cloud/cloud-services/scylla-cloud-managin-versions: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-managin-versions
+/scylla-cloud/cloud-services/scylla-cloud-support-alerts-sla: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-support-alerts-sla
+/scylla-cloud/cloud-services/scylla-cloud-value: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-value
+
+/scylla-cloud/cloud-setup/AWS: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS
+/scylla-cloud/cloud-setup/AWS/aws-vpc-peering: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/aws-vpc-peering
+/scylla-cloud/cloud-setup/AWS/cloud-prom-proxy: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/cloud-prom-proxy
+/scylla-cloud/cloud-setup/AWS/outposts: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/outposts
+/scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/scylla-cloud-byoa
+/scylla-cloud/cloud-setup/GCP: https://cloud.docs.scylladb.com/stable/cloud-setup/GCP
+/scylla-cloud/cloud-setup/GCP/gcp-vpc-peering: https://cloud.docs.scylladb.com/stable/cloud-setup/GCP/gcp-vpc-peering
+/scylla-cloud/cloud-setup/FAQ: https://cloud.docs.scylladb.com/stable/cloud-setup/FAQ
+/scylla-cloud/cloud-setup/scylla-best-practices: https://cloud.docs.scylladb.com/stable/cloud-setup/scylla-best-practices
+
+
+/scylla-cloud/learn-more: https://cloud.docs.scylladb.com/stable/learn-more
+
+/scylla-cloud/security: https://cloud.docs.scylladb.com/stable/security
+/scylla-cloud/security/best_practices: https://cloud.docs.scylladb.com/stable/security/best_practices
+/scylla-cloud/security/concepts: https://cloud.docs.scylladb.com/stable/security/concepts
+
diff --git a/docs/_utils/remove-redirection-loops.py b/docs/_utils/remove-redirection-loops.py
--- a/docs/_utils/remove-redirection-loops.py
+++ b/docs/_utils/remove-redirection-loops.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+# update redirection file to remove double redireaction
+# a->b, b->c, is rewritten ad a->c,b->c
+# write result to stdout
+
+import os
+import sys
+import re
+import yaml
+
+f = './redirections.yaml'
+new_f = './redirections.new.yaml'
+d = yaml.load(open(f), Loader=yaml.FullLoader)
+replace_dict = {}
+for key, value in d.items():
+ if value in d.keys():
+# print ("duble redirection:", key, "->", value, "->", d[value])
+ replace_dict[value] = d[value]
+
+with open(f, "r") as source:
+ lines = source.readlines()
+ for line in lines:
+ dline = yaml.safe_load(line)
+ if (dline is not None):
+ for key, value in dline.items():
+ if value in replace_dict.keys():
+ print (key, ": ", replace_dict[value],sep="")
+ else:
+ print(line, end='')
+ else:
+ print(line, end='')
+
diff --git a/docs/architecture/1-write_op_RF_3.jpg b/docs/architecture/1-write_op_RF_3.jpg
--- a/docs/architecture/1-write_op_RF_3.jpg
+++ b/docs/architecture/1-write_op_RF_3.jpg
null
diff --git a/docs/architecture/2-read_op_RF_3.jpg b/docs/architecture/2-read_op_RF_3.jpg
--- a/docs/architecture/2-read_op_RF_3.jpg
+++ b/docs/architecture/2-read_op_RF_3.jpg
null
diff --git a/docs/architecture/3-write_op_RF_3_CL_1.jpg b/docs/architecture/3-write_op_RF_3_CL_1.jpg
--- a/docs/architecture/3-write_op_RF_3_CL_1.jpg
+++ b/docs/architecture/3-write_op_RF_3_CL_1.jpg
null
diff --git a/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg b/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
--- a/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
+++ b/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_1.jpg b/docs/architecture/5-read_op_RF_3_CL_1.jpg
--- a/docs/architecture/5-read_op_RF_3_CL_1.jpg
+++ b/docs/architecture/5-read_op_RF_3_CL_1.jpg
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_1.xcf b/docs/architecture/5-read_op_RF_3_CL_1.xcf
--- a/docs/architecture/5-read_op_RF_3_CL_1.xcf
+++ b/docs/architecture/5-read_op_RF_3_CL_1.xcf
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_2.jpg b/docs/architecture/5-read_op_RF_3_CL_2.jpg
--- a/docs/architecture/5-read_op_RF_3_CL_2.jpg
+++ b/docs/architecture/5-read_op_RF_3_CL_2.jpg
null
diff --git a/docs/architecture/6-CAP_Theorem.jpg b/docs/architecture/6-CAP_Theorem.jpg
--- a/docs/architecture/6-CAP_Theorem.jpg
+++ b/docs/architecture/6-CAP_Theorem.jpg
null
diff --git a/docs/architecture/anti-entropy/1_read_repair.png b/docs/architecture/anti-entropy/1_read_repair.png
--- a/docs/architecture/anti-entropy/1_read_repair.png
+++ b/docs/architecture/anti-entropy/1_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/2_read_repair.png b/docs/architecture/anti-entropy/2_read_repair.png
--- a/docs/architecture/anti-entropy/2_read_repair.png
+++ b/docs/architecture/anti-entropy/2_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/3_read_repair.png b/docs/architecture/anti-entropy/3_read_repair.png
--- a/docs/architecture/anti-entropy/3_read_repair.png
+++ b/docs/architecture/anti-entropy/3_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/4_read_repair.png b/docs/architecture/anti-entropy/4_read_repair.png
--- a/docs/architecture/anti-entropy/4_read_repair.png
+++ b/docs/architecture/anti-entropy/4_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/5_read_repair.png b/docs/architecture/anti-entropy/5_read_repair.png
--- a/docs/architecture/anti-entropy/5_read_repair.png
+++ b/docs/architecture/anti-entropy/5_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png b/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
--- a/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
+++ b/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
null
diff --git a/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png b/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
--- a/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
+++ b/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-3.png b/docs/architecture/anti-entropy/hinted-handoff-3.png
--- a/docs/architecture/anti-entropy/hinted-handoff-3.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-3.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-4.png b/docs/architecture/anti-entropy/hinted-handoff-4.png
--- a/docs/architecture/anti-entropy/hinted-handoff-4.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-4.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-5.png b/docs/architecture/anti-entropy/hinted-handoff-5.png
--- a/docs/architecture/anti-entropy/hinted-handoff-5.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-5.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff.rst b/docs/architecture/anti-entropy/hinted-handoff.rst
--- a/docs/architecture/anti-entropy/hinted-handoff.rst
+++ b/docs/architecture/anti-entropy/hinted-handoff.rst
@@ -0,0 +1,49 @@
+Scylla Hinted Handoff
+=====================
+
+A typical write in Scylla works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.
+
+But what happens when a write request is sent to a Scylla node that is unresponsive due to reasons including heavy write load on a node, network issues, or even hardware failure? To ensure availability and consistency, Scylla implements :term:`hinted handoff<Hinted Handoff>`.
+
+ :term:`Hint<Hint>` = target replica ID + :term:`mutation<Mutation>` data
+
+
+In other words, Scylla saves a copy of the writes intended for down nodes, and replays them to the nodes when they are up later. Thus, the write operation flow, when a node is down, looks like this:
+
+1. The co-ordinator determines all the replica nodes;
+
+2. Based on the replication factor (RF) , the co-ordinator :doc:`attempts to write to RF nodes </architecture/architecture-fault-tolerance>`;
+
+.. image:: ../1-write_op_RF_3.jpg
+
+3. If one node is down, acknowledgments are only returned from two nodes:
+
+.. image:: hinted-handoff-3.png
+
+4. If the consistency level does not require responses from all replicas, the co-ordinator, *V* in this case, will respond to the client that the write was successful. The co-ordinator will write and store a :term:`hint<Hint>` for the missing node:
+
+.. image:: hinted-handoff-4.png
+
+5. Once the down node comes up, the co-ordinator will replay the hint for that node. After the co-ordinator receives an acknowledgement of the write, the hint is deleted.
+
+.. image:: hinted-handoff-5.png
+
+A co-ordinator stores hints for a handoff under the following conditions:
+
+1. For down nodes;
+2. If the replica doesn't respond within :code:`write_request_timeout_in_ms`.
+
+The co-ordinator will stop creating any hints for a dead node if the node's downtime is greater than :code:`max_hint_window_in_ms`.
+
+Hinted handoff is enabled and managed by these settings in :code:`scylla.yaml`:
+
+* :code:`hinted_handoff_enabled`: enables or disables the hinted handoff feature completely or enumerates data centers where hints are allowed. By default, “true” enables hints to all nodes.
+* :code:`max_hint_window_in_ms`: do not generate hints if the destination node has been down for more than this value. If a node is down longer than this period, new hints are not created. Hint generation resumes once the destination node is back up. By default, this is set to 3 hours.
+* :code:`hints_directory`: the directory where Scylla will store hints. By default this is :code:`$SCYLLA_HOME/hints`.
+
+Storing of the hint can also fail. Enabling hinted handoff therefore does not eliminate the need for repair; a user must recurrently :doc:`run a full repair </operating-scylla/procedures/maintenance/repair/>` to ensure data consistency across the cluster nodes.
+
+Hinted handoff was released as production-ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/anti-entropy/index.rst b/docs/architecture/anti-entropy/index.rst
--- a/docs/architecture/anti-entropy/index.rst
+++ b/docs/architecture/anti-entropy/index.rst
@@ -0,0 +1,34 @@
+Scylla Anti-Entropy
+===================
+
+.. toctree::
+ :hidden:
+ :glob:
+
+ Scylla Hinted Handoff <hinted-handoff/>
+ Scylla Read Repair <read-repair/>
+ Scylla Repair </operating-scylla/procedures/maintenance/repair/>
+
+
+Scylla replicates data according to :term:`eventual consistency<Eventual Consistency>`. This means that, in Scylla, when considering the :term:`CAP Theorem<CAP Theorem>`, availability and partition tolerance are considered a higher priority over consistency. Although Scylla’s tunable consistency allows users to make a tradeoff between availability and consistency, Scylla’s :term:`consistency level<Consistency Level (CL)>` is tunable per query.
+
+However, over time, there can be a number of reasons for data inconsistencies, including:
+
+1. a down node;
+2. a network partition;
+3. dropped mutations;
+4. process crashes (before a flush);
+5. a replica that cannot write due to being out of resources;
+6. file corruption.
+
+To mitigate :term:`entropy<Entropy>`, or data inconsistency, Scylla uses a few different processes. The goal of Scylla :term:`anti-entropy<Anti-Entropy>` - based on that of Apache Cassandra - is to compare data on all replicas, synchronize data between all replicas, and, finally, ensure each replica has the most recent data.
+
+Anti-entropy measures include *write-time* changes such as :term:`hinted handoff<Hinted Handoff>`, *read-time* changes such as :term:`read repair<Read Repair>`, and finally, periodic maintenance via :term:`repair<Repair>`.
+
+* :doc:`Scylla Hinted Handoff <hinted-handoff/>` - High-Level view of Scylla Hinted Handoff
+* :doc:`Scylla Read Repair <read-repair/>` - High-Level view of Scylla Read Repair
+* :doc:`Scylla Repair </operating-scylla/procedures/maintenance/repair/>` - Description of Scylla Repair
+
+Also learn more in the `Cluster Management, Repair and Scylla Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/topic/cluster-management-repair-and-scylla-manager/>`_ on Scylla University.
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/anti-entropy/read-repair.rst b/docs/architecture/anti-entropy/read-repair.rst
--- a/docs/architecture/anti-entropy/read-repair.rst
+++ b/docs/architecture/anti-entropy/read-repair.rst
@@ -0,0 +1,83 @@
+Scylla Read Repair
+==================
+
+Read repair serves as an anti-entropy mechanism during read path.
+
+On read operations, Scylla runs a process called :term:`read repair<Read Repair>`, to ensure that replicas are updated with most recently updated data. Such repairs during read path run automatically, asynchronously, and in the background.
+
+Note however, that if digest mismatch is detected before consistency level is reached, that repair will run in the foreground.
+
+A normal read operation works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.
+
+Read Request
+^^^^^^^^^^^^
+This image illustrates the flow of a read request, when data is out of sync, and a background read repair process is triggered.
+
+.. image:: 1_read_repair.png
+
+1. Our coordinator, *V*, **requests data** (including digest) from one node, *W*, which is out of date.
+
+2. The coordinator also **requests digests** from the number of nodes up to the consistency level (in this case, *Quorum* or 2) which, in this case, includes Node *X*.
+
+3. If the digests from all replicas match, the coordinator responds to the client with the read data. If there is a mismatch (shown above), a :term:`read repair<Read Repair>` is performed.
+
+Read Repair
+^^^^^^^^^^^
+See the appendices below for the detailed flow.
+
+1. Triggered by a mismatch in digest response from replicas (see above), the co-ordinator, in this case, node *V*, **sends requests (for the full data set)** to the same sub set of replicas participates in the read (up to the consistency level).
+
+.. image:: 2_read_repair.png
+
+2. During :term:`reconciliation<Reconciliation>`, the co-ordinator (Node *V*) compares full data sets, and **sends updates back** to the out-of-date nodes.
+
+.. image:: 3_read_repair.png
+
+3. Once all updated replicas successfully have responded, the co-ordinator **returns the merged data set** to the client.
+
+.. image:: 4_read_repair.png
+
+Probabilistic Read Repair
+^^^^^^^^^^^^^^^^^^^^^^^^^
+See the appendices below for the detailed flow.
+
+Another read repair mechanism is **probabilistic** read repair, which works as follows:
+
+1. The coordinator checks the value of the ``read_repair_chance`` or ``dclocal_read_repair_chance``. If the probability of a read repair is triggered, it will start the read repair across the entire cluster, or inside the DC, respectively.
+
+.. note::
+
+ These two settings are configured in ``scylla.yaml``.
+ In recent Scylla versions (starting from 4.2.0) default value of both parameters is zero, making Probabilistic Read Repair **off by default**, with a plan to `remove it in the future <https://github.com/scylladb/scylla/issues/3502>`_
+
+2. If the probability of a read repair is triggered, the coordinator sends data request to one of the nodes, digest request to all of the remaining nodes.
+
+.. image:: 5_read_repair.png
+
+3. The coordinator responds to the client as soon as there are enough replies to achieve consistency level, and there is a match.
+
+.. raw:: html
+
+
+
+4. After ALL replicas responses to the coordinator (which may have already responded to the client), the coordinator will compare all responses; and if required (there is a mismatch), the coordinator will ask for the data from all replicas, run reconciliation, and send deltas to any out-of-date replica node(s) - in the background.
+
+.. raw:: html
+
+
+
+5. If a query’s consistency level is more than 1, and a data mismatch is found before consistency level is reached, then the read repair will run in the foreground. **All replica nodes are updated before the data is returned to the client.** However, if data mismatch is found *after* a query’s consistency level is achieved, the update happens in the background, as mentioned above.
+
+The probability of this kind of read repair occurring on a read request is based on the :code:`read_repair_chance`. This :doc:`setting </getting-started/ddl/>`, provided when a table is created, can apply across data centers. The setting specifies the probability that extra nodes (in addition to those required by the consistency level) are queried for the purpose of read repairs.
+
+A similar :doc:`setting </getting-started/ddl/>`, :code:`dclocal_read_repair_chance`, applies only to nodes within the local data center. You can use this setting when conserving traffic between data centers is important.
+
+* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>`
+
+Appendix
+^^^^^^^^
+Flows created with `websequencediagrams.com <http://websequencediagrams.com>`_.
+
+.. image:: 6_Read_Path_with_Read_Repair.png
+
+.. image:: 7_Read_Path_with_Probabilistic_Read_Repair.png
diff --git a/docs/architecture/architecture-fault-tolerance.rst b/docs/architecture/architecture-fault-tolerance.rst
--- a/docs/architecture/architecture-fault-tolerance.rst
+++ b/docs/architecture/architecture-fault-tolerance.rst
@@ -0,0 +1,78 @@
+Scylla Architecture - Fault Tolerance
+=====================================
+
+Scylla replicates data according to a :term:`replication<Replication>` strategy that you choose. This strategy will determine the placement of the replicated data. Scylla runs nodes in a hash ring. All nodes are equal: there are no master, slave, or replica sets.
+
+The :term:`Replication Factor (RF)<Replication Factor (RF)>` is equivalent to the number of nodes where data (rows and partitions) are replicated. Data is replicated to multiple (RF=N) nodes.
+
+An RF of ``1`` means there is only one copy of a row in a cluster and there is no way to recover the data if the node is compromised or goes down. RF=2 means that there are two copies of a row in a cluster. An RF of at least ``3`` is used in most systems or similar.
+
+Data is always replicated automatically. **Read** or **write** operations can occur to data stored on any of the replicated nodes.
+
+.. image:: 1-write_op_RF_3.jpg
+
+In the example above, our client sends a request to write partition *1* to node *V*; 1’s data is replicated to nodes *W*, *X*, and *Z*. We have a Replication Factor (RF) of ``3``. In this drawing, *V* is a coordinator node but not a replicator node. However, replicator nodes can also be coordinator nodes, and often are.
+
+.. image:: 2-read_op_RF_3.jpg
+
+During a :term:`read operation<Read Operation>`, the client sends a request to the coordinator. Effectively because the RF=3, 3 nodes respond to the read request.
+
+The :term:`Consistency Level (CL)<Consistency Level (CL)>` determines how many replicas in a cluster must acknowledge read or :term:`write operations<Write Operation>` before it is considered successful.
+
+For the CQL Shell (:doc:`CQLsh </getting-started/cqlsh>`), the consistency level defaults to ONE for read and write operations.
+
+
+.. note::
+ Regardless of the **Consistency Level**, a write is always sent to *all* replicas, as set by the **Replication Factor**. Consistency Level control *when* a client acknowledged, not how many replicas are updated.
+
+During a write operation, the coordinator communicates with the replicas (the number of which depends on the Replication Factor). The write is successful when the specified number of replicas confirm the write.
+
+.. image:: 3-write_op_RF_3_CL_1.jpg
+
+In the above diagram, the double arrows indicate the write operation request going into the coordinator from the client and the acknowledgment being returned. Since the Consistency Level is one, the coordinator, *V*, must only wait for the write to be sent to and responded by a single node in the cluster which is *W*.
+
+Since RF=3, our partition 1 is also written to nodes *X* and *Z*, but the coordinator does not need to wait for a response from them to confirm a successful write operation. In practice, acknowledgments from nodes *X* and *Z* can arrive to the coordinator at a later time, after the coordinator acknowledges the client.
+
+When our Consistency Level is set to ``QUORUM``, the coordinator must wait for a majority of nodes to acknowledge the write before it is considered successful. Since our Replication Factor is 3, we must wait for 2 acknowledgments (the third acknowledgment does not need to be returned):
+
+.. image:: 4-write_op_RF_3_CL_Quorum.jpg
+
+During a read operation, the coordinator communicates with just enough replicas to guarantee that the required Consistency Level is met. Data is then returned to the client.
+
+
+.. image:: 5-read_op_RF_3_CL_2.jpg
+
+
+
+
+The Consistency Level is tunable per operation in CQL. This is known as :term:`tunable consistency<Tunable Consistency>`. Sometimes response latency is more important, making it necessary to adjust settings on a per-query or operation level to override keyspace or even data center-wide consistency settings. In other words, the Consistency Level setting allows you to choose a point in the consistency vs. latency tradeoff.
+
+.. note:: Quorum is a global consistency level across the *entire* cluster. This means that if you have two data centers, all nodes in both datacenters count towards the quorum majority. For example, there is a cluster with two DCs with three nodes in one DC and two nodes in the other. If the smaller DC fails, requests will still pass under Quorum as 3 > 5/2.
+
+The Consistency Level and Replication Factor both impact performance. The **lower** the Consistency Level and/or Replication Factor, the **faster** the read or write operation. However, there will be less fault tolerance if a node goes down.
+
+The Consistency Level itself impacts availability. A **higher** Consistency Level (more nodes required to be online) means less availability with less tolerance to tolerate node failures. A **lower** Consistency Level means more availability and more fault tolerance.
+
+Refer to the :ref:`Consistency Level table <consistency-levels-reference>` to get information about the Consistency Levels that are available for a read or write operation.
+
+Scylla, as do many distributed database systems, adheres to the :term:`CAP Theorem<CAP Theorem>`. The **CAP Theorem** is the notion that **Consistency**, **Availability** and **Partition Tolerance** of data are mutually dependent in a distributed system. Increasing any 2 of these factors will reduce the third.
+
+Scylla adheres to the CAP theorem in the following way:
+
+.. image:: 6-CAP_Theorem.jpg
+
+Scylla chooses availability and partition tolerance over consistency, such that:
+
+- It’s impossible to be both consistent and highly available during a network partition;
+
+- If we sacrifice consistency, we can be highly available.
+
+You’ll need to design your application around Scylla’s data modeling, but the net result is an application that will never go down.
+
+
+Additional Resources
+--------------------
+
+* :doc:`Consistency Level Console Demo </architecture/console-CL-full-demo>`
+* :doc:`Consistency Levels </getting-started/consistency/>`
+* From Scylla Univeristy: take the `Consistency Level lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/consistency-level-cl/>`_
diff --git a/docs/architecture/compaction/compaction-datawrites.png b/docs/architecture/compaction/compaction-datawrites.png
--- a/docs/architecture/compaction/compaction-datawrites.png
+++ b/docs/architecture/compaction/compaction-datawrites.png
null
diff --git a/docs/architecture/compaction/compaction-leveled.png b/docs/architecture/compaction/compaction-leveled.png
--- a/docs/architecture/compaction/compaction-leveled.png
+++ b/docs/architecture/compaction/compaction-leveled.png
null
diff --git a/docs/architecture/compaction/compaction-size-tiered.png b/docs/architecture/compaction/compaction-size-tiered.png
--- a/docs/architecture/compaction/compaction-size-tiered.png
+++ b/docs/architecture/compaction/compaction-size-tiered.png
null
diff --git a/docs/architecture/compaction/compaction-strategies.rst b/docs/architecture/compaction/compaction-strategies.rst
--- a/docs/architecture/compaction/compaction-strategies.rst
+++ b/docs/architecture/compaction/compaction-strategies.rst
@@ -0,0 +1,244 @@
+============================
+Choose a Compaction Strategy
+============================
+
+
+Scylla implements the following compaction strategies in order to reduce :term:`read amplification<Read Amplification>`, :term:`write amplification<Write Amplification>`, and :term:`space amplification<Space Amplification>`, which causes bottlenecks and poor performance. These strategies include:
+
+* `Size-tiered compaction strategy (STCS)`_ - triggered when the system has enough (four by default) similarly sized SSTables.
+* `Leveled compaction strategy (LCS)`_ - the system uses small, fixed-size (by default 160 MB) SSTables distributed across different levels.
+* `Incremental Compaction Strategy (ICS)`_ - shares the same read and write amplification factors as STCS, but it fixes its 2x temporary space amplification issue by breaking huge sstables into SSTable runs, which are comprised of a sorted set of smaller (1 GB by default), non-overlapping SSTables.
+* `Time-window compaction strategy (TWCS)`_ - designed for time series data; replaced Date-tiered compaction.
+* `Date-tiered compaction strategy (DTCS)`_ - designed for time series data.
+
+This document covers how to choose a compaction strategy and presents the benefits and disadvantages of each one. If you want more information on compaction in general or on any of these strategies, refer to the :doc:`Compaction Overview </kb/compaction>`. If you want an explanation of the CQL commands used to create a compaction strategy, refer to :doc:`Compaction CQL Reference </getting-started/compaction>` .
+
+Learn more in the `Compaction Strategies lesson <https://university.scylladb.com/courses/scylla-operations/lessons/compaction-strategies/>`_ on Scylla University
+
+.. _STCS1:
+
+Size-tiered Compaction Strategy (STCS)
+======================================
+
+The premise of :term:`Size-tiered Compaction Strategy (STCS)<Size-tiered Compaction Strategy>` is to merge SSTables of approximately the same size.
+
+Size-tiered compaction benefits
+-------------------------------
+This is a popular strategy for LSM workloads. It results in a low and logarithmic (in size of data) number of SSTables, and the same data is copied during compaction a fairly low number of times. Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+Size-tiered compaction disadvantages
+------------------------------------
+This strategy has the following drawbacks (particularly with writes):
+
+* Continuously modifying existing rows results in each row being split across several SSTables, making reads slow, which doesn’t happen in :ref:`Leveled compaction <LCS1>`.
+
+* Obsolete data (overwritten or deleted columns) in a very large SSTable remains, wasting space, for a long time, until it is finally merged. In overwrite-intensive loads for example, the overhead can be as much as 400%, as data will be duplicated 4X within a tier. On the other hand, the output SSTable will be the size of a single input SSTable. As a result, you will need 5X the amount of space (4 input SSTables plus one output SSTable), so 400% over the amount of data currently being stored. The allocated space will have to be checked and evaluated as your data set increases in size.
+
+* Compaction requires a lot of temporary space as the new larger SSTable is written before the duplicates are purged. In the worst case up to half the disk space needs to be empty to allow this to happen.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Size-tiered compaction <size-tiered-compaction-strategy-stcs>`.
+
+.. _LCS1:
+
+Leveled Compaction Strategy (LCS)
+=================================
+
+:term:`Leveled Compaction Strategy<Leveled compaction strategy (LCS)>` (LCS) uses small, fixed-size (by default 160 MB) SSTables divided into different levels. Each level represents a run of a number of SSTables.
+
+Leveled Compaction benefits
+---------------------------
+With the leveled compaction strategy, the following benefits are noteworthy:
+
+* SSTable reads are efficient. The great number of small SSTables doesn’t mean we need to look up a key in that many SSTables, because we know the SSTables in each level have disjoint ranges, so we only need to look in one SSTable in each level. In the typical case, only one SSTable needs to be read.
+* The other factors making this compaction strategy efficient are that at most 10% of space will be wasted by obsolete rows, and only enough space for ~10x the small SSTable size needs to be reserved for temporary use by compaction.
+
+Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+Leveled Compaction disadvantages
+--------------------------------
+The downside of this method is there is two times more I/O on writes, so it is not as good for workloads which focus on writing mostly new data.
+
+Only one compaction operation on the same table can run at a time, so compaction may be postponed if there is a compaction already in progress. As the size of the files is not too large, this is not really an issue.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Leveled Compaction <leveled-compaction-strategy-lcs>`.
+
+.. _ICS1:
+
+Incremental Compaction Strategy (ICS)
+=====================================
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. note:: ICS is only available for Scylla Enterprise customers
+
+ICS principles of operation are similar to those of STCS, merely replacing the increasingly larger SSTables in each tier, by increasingly longer SSTable runs, modeled after LCS runs, but using larger fragment size of 1 GB, by default.
+
+Compaction is triggered when there are two or more runs of roughly the same size. These runs are incrementally compacted with each other, producing a new SSTable run, while incrementally releasing space as soon as each SSTable in the input run is processed and compacted. This method eliminates the high temporary space amplification problem of STCS by limiting the overhead to twice the (constant) fragment size, per shard.
+
+Incremental Compaction Strategy benefits
+----------------------------------------
+* Greatly reduces the temporary space amplification which is typical of STCS, resulting in more disk space being available for storing user data.
+* The space requirement for a major compaction with ICS is almost non-existent given that the operation can release fragments at roughly same rate it produces new ones.
+
+If you look at the following screenshot the green line shows how disk usage behaves under ICS when major compaction is issued.
+
+.. image:: /architecture/compaction/screenshot.png
+
+Incremental Compaction Strategy disadvantages
+----------------------------------------------
+
+* Since ICS principles of operation are the same as STCS, its disadvantages are similar to STCS's, except for the temporary space amplification issue.
+
+Namely:
+
+* Continuously modifying existing rows results in each row being split across several SSTables, making reads slow, which doesn’t happen in Leveled compaction.
+* Obsolete data (overwritten or deleted columns) may accumulate across tiers, wasting space, for a long time, until it is finally merged. This can be mitigated by running major compaction from time to time.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Incremental Compaction <incremental-compaction-strategy-ics>`.
+
+For more information, see the :ref:`Compaction KB Article <incremental-compaction-strategy-ics>`.
+
+.. _TWCS1:
+
+Time-window Compaction Strategy (TWCS)
+======================================
+
+Time-window compaction strategy was introduced in Cassandra 3.0.8 for time-series data as a replacement for `Date-tiered Compaction Strategy (DTCS)`_.
+Time-Window Compaction Strategy compacts SSTables within each time window using `Size-tiered Compaction Strategy (STCS)`_.
+SSTables from different time windows are never compacted together. You set the :ref:`TimeWindowCompactionStrategy <time-window-compactionstrategy-twcs>` parameters when you create a table using a CQL command.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+Time-window Compaction benefits
+-------------------------------
+
+* Keeps entries according to a time range, making searches for data within a given range easy to do, resulting in better read performance
+* Improves over DTCS in that it reduces the number to huge compactions
+* Allows you to expire an entire SSTable at once (using a TTL) as the data is already organized within a time frame
+
+Time-window Compaction deficits
+-------------------------------
+
+* Time-window compaction is **only** ideal for time-series workloads
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Time-window Compaction <time-window-compactionstrategy-twcs>`.
+
+Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+.. _DTCS1:
+
+Date-tiered Compaction Strategy (DTCS)
+======================================
+
+Date-Tiered Compaction is designed for time series data. This strategy was introduced with Cassandra 2.1.
+It is only suitable for time-series data. This strategy is not recommended and has been replaced by :ref:`Time-window Compaction Strategy <TWCS1>`.
+
+.. _which-strategy-is-best:
+
+Which strategy is best
+======================
+
+Every workload type may not work well with every compaction strategy. Unfortunately, the more mixed your workload, the harder it is to pick the correct strategy. This table presents what can be expected depending on the strategy you use for the workload indicated, allowing you to make a more informed decision. Keep in mind that the best choice for our testing may not be the best choice for your environment. You may have to experiment to find which strategy works best for you.
+
+.. _CSM1:
+
+Compaction Strategy Matrix
+--------------------------
+
+The table presents which workload works best with which compaction strategy. In cases where you have the ability to use either STCS or ICS, always choose ICS.
+
+.. list-table::
+ :widths: 20 15 15 15 15 20
+ :header-rows: 1
+
+ * - Workload/Compaction Strategy
+ - Size-tiered
+ - Leveled
+ - Incremental
+ - Time-Window
+ - Comments
+ * - Write-only
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [1]_ and [2]_
+ * - :abbr:`Overwrite (Same data cells overwritten many times)`
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [3]_ and [4]_
+ * - Read-mostly, with few updates
+ - |x|
+ - |v|
+ - |x|
+ - |x|
+ - [5]_
+ * - Read-mostly, with many updates
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [6]_
+ * - Time Series
+ - |x|
+ - |x|
+ - |x|
+ - |v|
+ - [7]_ and [8]_
+
+
+The comments below describe the type of amplification each compaction strategy create on each use case, using the following abbreviations:
+
+* SA - Size Amplification
+* WA - Write Amplification
+* RA - Read Amplification
+
+.. _1:
+
+:sup:`1` When using Size-tiered with write-only loads it will use approximately 2x peak space - :abbr:`SA (Size Amplification)` with Incremental, the SA is much less
+
+.. _2:
+
+:sup:`2` When using Leveled Compaction with write only loads you will experience high Write Amplification - :abbr:`WA (Write Amplification)`
+
+.. _3:
+
+:sup:`3` When using Size-tired or Incremental with Overwrite loads, :abbr:`SA (Size Amplification)` occurs
+
+.. _4:
+
+:sup:`4` When using Leveled Compaction with overwrite loads, :abbr:`WA (Write Amplification)` occurs
+
+.. _5:
+
+:sup:`5` When using Size-tiered with mostly read loads with little updates, :abbr:`SA (Size Amplification)` and :abbr:`RA (Read Amplification)` occurs
+
+.. _6:
+
+:sup:`6` When using Leveled with mostly read loads with many updates, :abbr:`WA (Write Amplification)` occurs in excess
+
+.. _7:
+
+:sup:`7` When using Size-tiered or Incremental with Time Series workloads, :abbr:`SA (Size Amplification)`, :abbr:`RA (Read Amplification)`, and :abbr:`WA (Write Amplification)` occurs.
+
+.. _8:
+
+:sup:`8` When using Leveled with Time Series workloads, :abbr:`SA (Size Amplification)` and :abbr:`WA (Write Amplification)` occurs.
+
+References
+----------
+* :doc:`Compaction Overview </kb/compaction>` - contains in depth information on all of the strategies
+* :doc:`Compaction CQL Reference </getting-started/compaction>` - covers the CQL parameters used for implementing compaction
+* Scylla Summit Tech Talk: `How to Ruin Performance by Choosing the Wrong Compaction Strategy <https://www.scylladb.com/tech-talk/ruin-performance-choosing-wrong-compaction-strategy-scylla-summit-2017/>`_
+
+
diff --git a/docs/architecture/compaction/screenshot.png b/docs/architecture/compaction/screenshot.png
--- a/docs/architecture/compaction/screenshot.png
+++ b/docs/architecture/compaction/screenshot.png
null
diff --git a/docs/architecture/console-CL-full-demo.rst b/docs/architecture/console-CL-full-demo.rst
--- a/docs/architecture/console-CL-full-demo.rst
+++ b/docs/architecture/console-CL-full-demo.rst
@@ -0,0 +1,236 @@
+Consistency Level Console Demo
+==============================
+In this demo, we'll bring up 3 nodes and demonstrate how writes and reads look, with tracing enabled in a cluster where our :term:`Replication Factor (RF)<Replication Factor (RF)>` is set to **3**. We'll change the :term:`Consistency Level (CL)<Consistency Level (CL)>` between operations to show how messages are passed between nodes, and finally take down a few nodes to show failure conditions in a Scylla cluster.
+
+You can also learn more in the `High Availability lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability//>`_ on Scylla University.
+
+
+Note: We use asciinema_ to generate the console casts used in this demo. These asciicasts are more readable than embedded video, and allow you to copy the text or commands directly from the console to your clipboard. We suggest viewing console casts in **fullscreen** to see the properly formatted output.
+
+.. _asciinema: https://asciinema.org
+
+
+Step one: bring up the cluster
+-------------------------------
+
+First, we'll bring up a 3-node docker cluster. You'll see all the nodes eventually read ``UN`` for status. ``U`` means **up**, and ``N`` means **normal**. Read more about :doc:`Nodetool Status </operating-scylla/nodetool-commands/status/>`.
+
+Once all nodes are up, we can run our CQL shell.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/SQ5KW0bYTjXRWPHVkGY97WD1A.js" id="asciicast-SQ5KW0bYTjXRWPHVkGY97WD1A" data-speed="3" data-rows="30" autoplay=1 async></script>
+ </div>
+ </div>
+
+We've run ``nodetool status`` after we've waited for all nodes to come up:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Datacenter: datacenter1
+ =======================
+ Status=Up/Down
+ |/ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 172.17.0.3 127.42 KB 256 65.8% 66a3bfe7-3e90-4859-a394-becc00af1cf2 rack1
+ UN 172.17.0.2 110.58 KB 256 65.5% f66639bf-3259-47f5-8487-602fcb082624 rack1
+ UN 172.17.0.4 118.38 KB 256 68.6% d978ff65-0331-4f27-a129-9be2d7169ad6 rack1
+
+
+Step two: take a single node down, check different consistency levels
+----------------------------------------------------------------------
+
+So, what happens when we take a single node down? Here, we'll take a single node down, check status with ``nodetool``, attempt a write with **ALL** and **QUORUM** consistency levels.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/KhUpcnsWgpu119psj5aHjac0N.js" id="asciicast-KhUpcnsWgpu119psj5aHjac0N" data-speed="3" data-rows="40" async></script>
+ </div>
+ </div>
+
+Note that we've turned tracing off. We can observe that our **CL=ALL** writes will always fail because one of the nodes is down. **CL=QUORUM** operations *could* fail, depending on whether a required partition replica falls on a node that is up or down.
+
+
+Step three: take 2 nodes down, read and write with different consistency levels
+--------------------------------------------------------------------------------
+
+Let's take a second node down and attempt to read and write with QUORUM and ONE consistency levels.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/dkTt8Lopfa6N1VsajcmjUsduK.js" id="asciicast-dkTt8Lopfa6N1VsajcmjUsduK" data-speed="3" data-rows="40" async></script>
+ </div>
+ </div>
+
+With 2 nodes down on our 3 node cluster and **RF=3**, a **CL=QUORUM** will always fail as at least one of the required nodes will always be down. One the other hand, a **CL=ONE** will succeed, as it only requires one up node.
+
+
+Step four: testing different consistency levels with tracing on
+---------------------------------------------------------------
+
+Finally, we'll turn on tracing, and with all our nodes up, write to the table with **CL=ALL** and read from it with **CL=QUORUM**.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/LLOZIhQxX96BXsnrMpr50oUSa.js" id="asciicast-LLOZIhQxX96BXsnrMpr50oUSa" data-speed="3" data-t="103" autoplay=1 data-rows="30" async></script>
+ </div>
+ </div>
+
+
+We've just written a record with our consistency level set to ALL.
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> CONSISTENCY ALL
+
+Consistency level set to ALL.
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> CREATE TABLE users(user_id int PRIMARY KEY, fname text, lname text);
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> TRACING ON
+
+Now Tracing is enabled
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> insert into users(user_id, lname, fname) values (1, 'tzach', 'livyatan');
+
+
+Here's the output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Tracing session: 84deb7a0-9d81-11e7-b770-000000000002
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-19 21:28:46.362000 | 172.17.0.4 | 0
+ Parsing a statement [shard 0] | 2017-09-19 21:28:46.362223 | 172.17.0.4 | 14
+ Processing a statement [shard 0] | 2017-09-19 21:28:46.362604 | 172.17.0.4 | 273
+ Creating write handler for token: -4069959284402364209 | 2017-09-19 21:28:46.362962 | 172.17.0.4 | 755
+ natural: {172.17.0.3, 172.17.0.4, 172.17.0.2} pending: {} [shard 0] | | |
+ Creating write handler with live: {172.17.0.2, 172.17.0.3, 172.17.0.4} | 2017-09-19 21:28:46.362992 | 172.17.0.4 | 784
+ dead: {} [shard 0] | | |
+ Sending a mutation to /172.17.0.2 [shard 0] | 2017-09-19 21:28:46.363171 | 172.17.0.4 | 959
+ Sending a mutation to /172.17.0.3 [shard 0] | 2017-09-19 21:28:46.363298 | 172.17.0.4 | 1090
+ Executing a mutation locally [shard 0] | 2017-09-19 21:28:46.363316 | 172.17.0.4 | 1109
+ Message received from /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.363942 | 172.17.0.3 | 16
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.364225 | 172.17.0.3 | 307
+ Message received from /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.365395 | 172.17.0.2 | 93
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.365561 | 172.17.0.2 | 206
+ Mutation handling is done [shard 1] | 2017-09-19 21:28:46.366538 | 172.17.0.2 | 1234
+ Got a response from /172.17.0.2 [shard 0] | 2017-09-19 21:28:46.368064 | 172.17.0.4 | 5858
+ Got a response from /172.17.0.4 [shard 0] | 2017-09-19 21:28:46.369589 | 172.17.0.4 | 7384
+ Mutation handling is done [shard 1] | 2017-09-19 21:28:46.370843 | 172.17.0.3 | 6928
+ Got a response from /172.17.0.3 [shard 0] | 2017-09-19 21:28:46.372486 | 172.17.0.4 | 9964
+ Mutation successfully completed [shard 0] | 2017-09-19 21:28:46.372519 | 172.17.0.4 | 10314
+ Done processing - preparing a result [shard 0] | 2017-09-19 21:28:46.372548 | 172.17.0.4 | 10341
+ Request complete | 2017-09-19 21:28:46.372357 | 172.17.0.4 | 10357
+
+
+With tracing on, we have verbose output. Also, with all nodes up, we should have no errors experiencing a **CL=ALL** write. (Later, we will try different consistency levels with 1 and 2 nodes down.) With **RF=3**, we see all three nodes involved in the interaction. Once the co-ordinator (``172.17.0.4``) has received responses from the two other replicas - ``172.17.0.2`` and ``172.17.0.3`` - as well as itself- the operation is complete.
+
+So what happens when we write under **QUORUM** instead of **ALL**? **QUORUM** means that we only require responses from (Replication Factor/2) + 1 nodes. Our replication factor is 3, therefore only a majority of 2 nodes must provide an acknowledgement for the eventually-consistent write to be considered successful. Below, we observe that our coordinator, after sending two other mutations to replicas ``172.17.0.2`` and ``172.17.0.3``, executes a mutation locally. However, our coordinator only requires a write acknowledgement from itself and ``172.17.0.3`` before ``Mutation successfully completed`` is returned. Note that the response from ``172.17.0.2`` actually comes later.
+
+.. code:: console
+
+ cqlsh:mykeyspace> CONSISTENCY QUORUM
+
+Consistency level set to QUORUM.
+
+.. code:: console
+
+ cqlsh:mykeyspace> insert into users (user_id, fname, lname) values (2, 'john', 'hammink');
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Tracing session: ccb9d1d0-98d7-11e7-b971-000000000003
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-13 23:03:47.821000 | 172.17.0.4 | 0
+ Parsing a statement [shard 3] | 2017-09-13 23:03:47.821879 | 172.17.0.4 | 1
+ Processing a statement [shard 3] | 2017-09-13 23:03:47.822050 | 172.17.0.4 | 172
+ Creating write handler for token: -3248873570005575792 | 2017-09-13 23:03:47.822160 | 172.17.0.4 | 283
+ natural: {172.17.0.3, 172.17.0.4, 172.17.0.2} pending: {} [shard 3] | | |
+ Creating write handler with live: {172.17.0.2, 172.17.0.3, 172.17.0.4} | 2017-09-13 23:03:47.822171 | 172.17.0.4 | 293
+ dead: {} [shard 3] | | |
+ Sending a mutation to /172.17.0.2 [shard 3] | 2017-09-13 23:03:47.822192 | 172.17.0.4 | 314
+ Sending a mutation to /172.17.0.3 [shard 3] | 2017-09-13 23:03:47.822209 | 172.17.0.4 | 331
+ Executing a mutation locally [shard 3] | 2017-09-13 23:03:47.822214 | 172.17.0.4 | 336
+ Message received from /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.822564 | 172.17.0.2 | 7
+ Message received from /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.822851 | 172.17.0.3 | 5
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.823009 | 172.17.0.2 | 452
+ Mutation handling is done [shard 1] | 2017-09-13 23:03:47.823067 | 172.17.0.2 | 510
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.823734 | 172.17.0.3 | 887
+ Mutation handling is done [shard 1] | 2017-09-13 23:03:47.823744 | 172.17.0.3 | 898
+ Got a response from /172.17.0.4 [shard 3] | 2017-09-13 23:03:47.823984 | 172.17.0.4 | 2106
+ Got a response from /172.17.0.3 [shard 3] | 2017-09-13 23:03:47.824998 | 172.17.0.4 | 3120
+ Mutation successfully completed [shard 3] | 2017-09-13 23:03:47.825003 | 172.17.0.4 | 3125
+ Done processing - preparing a result [shard 3] | 2017-09-13 23:03:47.825054 | 172.17.0.4 | 3176
+ Got a response from /172.17.0.2 [shard 3] | 2017-09-13 23:03:47.825696 | 172.17.0.4 | 3817
+ Request complete | 2017-09-13 23:03:47.824182 | 172.17.0.4 | 3182
+
+
+We can observe that reading under **QUORUM** consistency works similarly. In our example below, our coordinator ``172.17.0.4`` waits for only ``read_data`` from ``172.17.0.2`` (as well as itself earlier: ``read_data: querying locally``) before the read is considered successful. Note that node ``172.17.0.3`` similarly handles ``read_digest`` as ``172.17.0.2`` handles ``read_data``.
+
+.. code:: console
+
+ cqlsh:mykeyspace> CONSISTENCY QUORUM
+
+Consistency level set to QUORUM.
+
+.. code:: console
+
+ cqlsh:mykeyspace> select * from users where user_id = 1;
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ user_id | fname | lname
+ ---------+-------+----------
+ 1 | tzach | livyatan
+
+ (1 rows)
+
+ Tracing session: b11084e0-9e33-11e7-9f6b-000000000003
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-20 18:44:10.926000 | 172.17.0.4 | 0
+ Parsing a statement [shard 3] | 2017-09-20 18:44:10.926442 | 172.17.0.4 | 1
+ Processing a statement [shard 3] | 2017-09-20 18:44:10.926538 | 172.17.0.4 | 97
+ Creating read executor for token -4069959284402364209 | 2017-09-20 18:44:10.926606 | 172.17.0.4 | 165
+ with all: {172.17.0.4, 172.17.0.2, 172.17.0.3} | | |
+ targets: {172.17.0.4, 172.17.0.2, 172.17.0.3} | | |
+ repair decision: DC_LOCAL [shard 3] | | |
+ read_digest: sending a message to /172.17.0.3 [shard 3] | 2017-09-20 18:44:10.926634 | 172.17.0.4 | 193
+ read_data: querying locally [shard 3] | 2017-09-20 18:44:10.926664 | 172.17.0.4 | 223
+ read_data: sending a message to /172.17.0.2 [shard 3] | 2017-09-20 18:44:10.926711 | 172.17.0.4 | 270
+ read_digest: message received from /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.926956 | 172.17.0.3 | 6
+ read_data: message received from /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.927310 | 172.17.0.2 | 7
+ read_digest handling is done, sending a response to /172.17.0.4 [shard 3]| 2017-09-20 18:44:10.927454 | 172.17.0.3 | 505
+ read_data handling is done, sending a response to /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.928248 | 172.17.0.2 | 946
+ read_digest: got response from /172.17.0.3 [shard 3] | 2017-09-20 18:44:10.929873 | 172.17.0.4 | 3432
+ read_data: got response from /172.17.0.2 [shard 3] | 2017-09-20 18:44:10.929880 | 172.17.0.4 | 3439
+ Done processing - preparing a result [shard 3] | 2017-09-20 18:44:10.929934 | 172.17.0.4 | 3493
+ Request complete | 2017-09-20 18:44:10.929503 | 172.17.0.4 | 3503
diff --git a/docs/architecture/fault-tolerance-operations-5.png b/docs/architecture/fault-tolerance-operations-5.png
--- a/docs/architecture/fault-tolerance-operations-5.png
+++ b/docs/architecture/fault-tolerance-operations-5.png
null
diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst
--- a/docs/architecture/index.rst
+++ b/docs/architecture/index.rst
@@ -0,0 +1,24 @@
+Scylla Architecture
+===================
+.. toctree::
+ :titlesonly:
+ :hidden:
+
+ Scylla Ring Architecture <ringarchitecture/index/>
+ Scylla Fault Tolerance <architecture-fault-tolerance>
+ Consistency Level Console Demo <console-CL-full-demo>
+ Scylla Anti-Entropy <anti-entropy/index/>
+ SSTable <sstable/index/>
+ Compaction Strategies <compaction/compaction-strategies>
+ Raft Consensus Algorithm in ScyllaDB </architecture/raft>
+
+
+* :doc:`Scylla Ring Architecture </architecture/ringarchitecture/index/>` - High-Level view of Scylla Ring Architecture
+* :doc:`Scylla Fault Tolerance </architecture/architecture-fault-tolerance>` - Deep dive into Scylla Fault Tolerance
+* :doc:`Consistency Level Console Demo </architecture/console-CL-full-demo>` - Console Demos of Consistency Level Settings
+* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>` - High-Level view of Scylla Anti-Entropy
+* :doc:`SSTable </architecture/sstable/index/>` - Scylla SSTable 2.0 and 3.0 Format Information
+* :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>` - High-level analysis of different compaction strategies
+* :doc:`Raft Consensus Algorithm in ScyllaDB </architecture/raft>` - Overview of how Raft is implemented in ScyllaDB.
+
+Learn more about these topics in the `Scylla University: Architecture lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/>`_.
diff --git a/docs/architecture/raft.rst b/docs/architecture/raft.rst
--- a/docs/architecture/raft.rst
+++ b/docs/architecture/raft.rst
@@ -0,0 +1,185 @@
+=========================================
+Raft Consensus Algorithm in ScyllaDB
+=========================================
+
+Introduction
+--------------
+ScyllaDB was originally designed, following Apache Cassandra, to use gossip for topology and schema updates and the Paxos consensus algorithm for
+strong data consistency (:doc:`LWT </using-scylla/lwt>`). To achieve stronger consistency without performance penalty, ScyllaDB 5.0 is turning to Raft - a consensus algorithm designed as an alternative to both gossip and Paxos.
+
+.. _raft-quorum-requirement:
+
+Quorum Requirement
+-------------------
+
+Raft requires at least a quorum of nodes in a cluster to be available. If multiple nodes fail
+and the quorum is lost, the cluster is unavailable for schema updates. See :ref:`Handling Failures <raft-handliing-failures>`
+for information on how to handle failures.
+
+
+Upgrade Considerations for SyllaDB 5.0 and Later
+==================================================
+
+Note that when you have a two-DC cluster with the same number of nodes in each DC, the cluster will lose the quorum if one
+of the DCs is down.
+**We recommend configuring three DCs per cluster to ensure that the cluster remains available and operational when one DC is down.**
+
+Enabling Raft
+---------------
+
+Enabling Raft in ScyllaDB 5.0
+===============================
+
+.. note::
+ In ScyllaDB 5.0:
+
+ * Raft is an experimental feature.
+ * Raft implementation only covers safe schema changes. See :ref:`Safe Schema Changes with Raft <raft-schema-changes>`.
+
+If you are creating a new cluster, add ``raft`` to the list of experimental features in your ``scylla.yaml`` file:
+
+.. code-block:: yaml
+
+ experimental_features:
+ - raft
+
+If you upgrade to ScyllaDB 5.0 from an earlier version, perform a :doc:`rolling restart </operating-scylla/procedures/config-change/rolling-restart/>`
+updating the ``scylla.yaml`` file for **each node** in the cluster to enable the experimental Raft feature:
+
+.. code-block:: yaml
+
+ experimental_features:
+ - raft
+
+
+When all the nodes in the cluster and updated and restarted, the cluster will begin to use Raft for schema changes.
+
+.. warning::
+ Once enabled, Raft cannot be disabled on your cluster. The cluster nodes will fail to restart if you remove the Raft feature.
+
+Verifying that Raft Is Enabled
+===============================
+You can verify that Raft is enabled on your cluster in one of the following ways:
+
+* Retrieve the list of supported features by running:
+
+ .. code-block:: sql
+
+ cqlsh> SELECT supported_features FROM system.local;
+
+ With Raft enabled, the list of supported features in the output includes ``SUPPORTS_RAFT_CLUSTER_MANAGEMENT``. For example:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ supported_features
+ -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ CDC,CDC_GENERATIONS_V2,COMPUTED_COLUMNS,CORRECT_COUNTER_ORDER,CORRECT_IDX_TOKEN_IN_SECONDARY_INDEX,CORRECT_NON_COMPOUND_RANGE_TOMBSTONES,CORRECT_STATIC_COMPACT_IN_MC,COUNTERS,DIGEST_FOR_NULL_VALUES,DIGEST_INSENSITIVE_TO_EXPIRY,DIGEST_MULTIPARTITION_READ,HINTED_HANDOFF_SEPARATE_CONNECTION,INDEXES,LARGE_PARTITIONS,LA_SSTABLE_FORMAT,LWT,MATERIALIZED_VIEWS,MC_SSTABLE_FORMAT,MD_SSTABLE_FORMAT,ME_SSTABLE_FORMAT,NONFROZEN_UDTS,PARALLELIZED_AGGREGATION,PER_TABLE_CACHING,PER_TABLE_PARTITIONERS,RANGE_SCAN_DATA_VARIANT,RANGE_TOMBSTONES,ROLES,ROW_LEVEL_REPAIR,SCHEMA_TABLES_V3,SEPARATE_PAGE_SIZE_AND_SAFETY_LIMIT,STREAM_WITH_RPC_STREAM,SUPPORTS_RAFT_CLUSTER_MANAGEMENT,TOMBSTONE_GC_OPTIONS,TRUNCATION_TABLE,UDA,UNBOUNDED_RANGE_TOMBSTONES,VIEW_VIRTUAL_COLUMNS,WRITE_FAILURE_REPLY,XXHASH
+
+* Retrieve the list of experimental features by running:
+
+ .. code-block:: sql
+
+ cqlsh> SELECT value FROM system.config WHERE name = 'experimental_features'
+
+ With Raft enabled, the list of experimental features in the output includes ``raft``.
+
+.. _raft-schema-changes:
+
+Safe Schema Changes with Raft
+-------------------------------
+In ScyllaDB, schema is based on :doc:`Data Definition Language (DDL) <../getting-started/ddl>`. In earlier ScyllaDB versions, schema changes were tracked via the gossip protocol, which might lead to schema conflicts if the updates are happening concurrently.
+
+Implementing Raft eliminates schema conflicts and allows full automation of DDL changes under any conditions, as long as a quorum
+of nodes in the cluster is available. The following examples illustrate how Raft provides the solution to problems with schema changes.
+
+* A network partition may lead to a split-brain case, where each subset of nodes has a different version of the schema.
+
+ With Raft, after a network split, the majority of the cluster can continue performing schema changes, while the minority needs to wait until it can rejoin the majority. Data manipulation statements on the minority can continue unaffected, provided the :ref:`quorum requirement <raft-quorum-requirement>` is satisfied.
+
+* Two or more conflicting schema updates are happening at the same time. For example, two different columns with the same definition are simultaneously added to the cluster. There is no effective way to resolve the conflict - the cluster will employ the schema with the most recent timestamp, but changes related to the shadowed table will be lost.
+
+ With Raft, concurrent schema changes are safe.
+
+
+
+In summary, Raft makes schema changes safe, but it requires that a quorum of nodes in the cluster is available.
+
+
+.. _raft-handliing-failures:
+
+Handling Failures
+------------------
+Raft requires a quorum of nodes in a cluster to be available. If one or more nodes are down, but the quorum is live, reads, writes,
+and schema udpates proceed unaffected.
+When the node that was down is up again, it first contacts the cluster to fetch the latest schema and then starts serving queries.
+
+The following examples show the recovery actions depending on the number of nodes and DCs in your cluster.
+
+Examples
+=========
+
+.. list-table:: Cluster A: 1 datacenter, 3 nodes
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1 node
+ - Schema updates are possible and safe.
+ - Try restarting the node. If the node is dead, :doc:`replace it with a new node </operating-scylla/procedures/cluster-management/replace-dead-node/>`.
+ * - 2 nodes
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - Restart at least 1 of the 2 nodes that are down to regain quorum. If you can’t recover at least 1 of the 2 nodes, contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+ * - 1 datacenter
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DC comes back online, restart the nodes. If the DC does not come back online and nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. list-table:: Cluster B: 2 datacenters, 6 nodes (3 nodes per DC)
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1-2 nodes
+ - Schema updates are possible and safe.
+ - Try restarting the node(s). If the node is dead, :doc:`replace it with a new node </operating-scylla/procedures/cluster-management/replace-dead-node/>`.
+ * - 3 nodes
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - Restart 1 of the 3 nodes that are down to regain quorum. If you can’t recover at least 1 of the 3 failed nodes, contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+ * - 1DC
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DCs come back online, restart the nodes. If the DC fails to come back online and the nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. list-table:: Cluster C: 3 datacenter, 9 nodes (3 nodes per DC)
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1-4 nodes
+ - Schema updates are possible and safe.
+ - Try restarting the nodes. If the nodes are dead, :doc:`replace them with new nodes </operating-scylla/procedures/cluster-management/replace-dead-node-or-more/>`.
+ * - 1 DC
+ - Schema updates are possible and safe.
+ - When the DC comes back online, try restarting the nodes in the cluster. If the nodes are dead, :doc:`add 3 new nodes in a new region </operating-scylla/procedures/cluster-management/add-dc-to-existing-dc/>`.
+ * - 2 DCs
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DCs come back online, restart the nodes. If at least one DC fails to come back online and the nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. _raft-learn-more:
+
+Learn More About Raft
+----------------------
+* `The Raft Consensus Algorithm <https://raft.github.io/>`_
+* `Achieving NoSQL Database Consistency with Raft in ScyllaDB <https://www.scylladb.com/tech-talk/achieving-nosql-database-consistency-with-raft-in-scylla/>`_ - A tech talk by Konstantin Osipov
+* `Making Schema Changes Safe with Raft <https://www.scylladb.com/presentations/making-schema-changes-safe-with-raft/>`_ - A Scylla Summit talk by Konstantin Osipov (register for access)
+* `The Future of Consensus in ScyllaDB 5.0 and Beyond <https://www.scylladb.com/presentations/the-future-of-consensus-in-scylladb-5-0-and-beyond/>`_ - A Scylla Summit talk by Tomasz Grabiec (register for access)
+
+
diff --git a/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif b/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
--- a/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
+++ b/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
null
diff --git a/docs/architecture/ringarchitecture/CodeCogsEqn.gif b/docs/architecture/ringarchitecture/CodeCogsEqn.gif
--- a/docs/architecture/ringarchitecture/CodeCogsEqn.gif
+++ b/docs/architecture/ringarchitecture/CodeCogsEqn.gif
null
diff --git a/docs/architecture/ringarchitecture/index.rst b/docs/architecture/ringarchitecture/index.rst
--- a/docs/architecture/ringarchitecture/index.rst
+++ b/docs/architecture/ringarchitecture/index.rst
@@ -0,0 +1,121 @@
+Scylla Ring Architecture - Overview
+===================================
+
+Scylla is a database that scales out and up. Scylla adopted much of its distributed scale-out design from the Apache Cassandra project (which adopted distribution concepts from Amazon Dynamo and data modeling concepts from Google BigTable).
+
+In the world of big data, a single node cannot hold the entire dataset and thus, a cluster of nodes is needed.
+
+A Scylla :term:`cluster<Cluster>` is a collection of :term:`nodes<Node>`, or Scylla instances, visualized as a ring. All of the nodes should be homogenous using a shared-nothing approach. This article describes the design that determines how data is distributed among the cluster members.
+
+A Scylla :term:`keyspace<Keyspace>` is a collection of tables with attributes that define how data is replicated on nodes. A keyspace is analogous to a database in SQL. When a new keyspace is created, the user sets a numerical attribute, the :term:`replication factor<Replication Factor (RF)>`, that defines how data is replicated on nodes. For example, an :abbr:`RF (Replication Factor)` of 2 means a given token or token range will be stored on 2 nodes (or replicated on one additional node). We will use an RF value of 2 in our examples.
+
+A :term:`table<Table>` is a standard collection of columns and rows, as defined by a schema. Subsequently, when a table is created, using CQL (Cassandra Query Language) within a keyspace, a primary key is defined out of a subset of the table’s columns.
+
+The table in the diagram below can thus be defined in CQL as follows:
+
+.. code-block:: SQL
+
+ CREATE TABLE users (
+ ID int,
+ NAME text,
+ ADDRESS text,
+ PHONE text,
+ PHONE_2 text,
+ PRIMARY KEY (ID)
+ );
+
+
+In a CQL table definition, the :term:`primary key<Primary Key>` clause specifies, at a minimum, a single column :term:`partition key<Partition key>` and may also specify :term:`clustering key<Clustering Key>` columns. The primary key uniquely identifies each partition/row combination in the table, while the clustering keys dictate how the data (rows) are sorted within a given partition. For more information, see our CQL :ref:`documentation <create-table-statement>`.
+
+A **row** is a container for columns associated with a primary key. In other words, a primary key represents one or more columns needed to fetch data from a CQL table.
+
+.. image:: ring-architecture-1.png
+
+A :term:`token<Token>` is a value in a range, used to identify both nodes and partitions. The :term:`partition key<Partition key>` is the unique identifier for a partition, and represented as a token which is hashed from the :term:`primary key<Primary Key>`.
+
+A :term:`partition<Partition>` is a subset of data that is stored on a node and replicated across nodes. There are two ways to consider a partition. In **CQL**, a partition appears as a group of sorted rows, and is the unit of access for queried data, given that most queries access a single partition. On the **physical layer**, a partition is a unit of data stored on a node and is identified by a :term:`partition key<Partition Key>`.
+
+In the diagram above, there are 3 partitions shown, with the partition keys of **101**, **103**, and **104**.
+
+A :term:`partition key<Partition key>` is the primary means of looking up a set of rows that comprise a partition. A partition key serves to identify the node in the cluster that stores a given partition, as well as to distribute data across nodes in a cluster.
+
+The :term:`partitioner<Partitioner>`, or **partition hash function**, using a partition key, determines where data is stored on a given node in the cluster. It does this by computing a token for each partition key. By default, the partition key is hashed using the Murmur3 hashing function.
+
+.. image:: ring-architecture-2.png
+
+The hashed output of the partition key determines its placement within the cluster.
+
+.. image:: ring-architecture-3.png
+
+The figure above illustrates an example 0-1200 token range divided evenly amongst a three node cluster.
+
+Scylla, by default, uses the Murmur3 partitioner. With the MurmurHash3 function, the 64-bit hash values (produced for the partition key) range from |From| to |To|. This explains why there are also negative values in our ``nodetool ring`` output below.
+
+.. |From| image:: CodeCogsEqn.gif
+.. |To| image:: CodeCogsEqn-2.gif
+
+.. image:: ring-architecture-4.png
+
+In the drawing above, each number represents a token range. With a replication factor of 2, we see that each node holds one range from the previous node, and one range from the next node.
+
+Note, however, that Scylla exclusively uses a Vnode-oriented architecture. A :term:`Virtual node` represents a contiguous range of tokens owned by a single Scylla node. A physical node may be assigned multiple, non-contiguous Vnodes.
+
+Scylla’s implementation of a Vnode oriented architecture provides several advantages. First of all, rebalancing a cluster is no longer required when adding or removing nodes. Secondly, as rebuilding can stream data from all available nodes (instead of just the nodes where data would reside on a one-token-per-node setup), Scylla can rebuild faster.
+
+.. image:: ring-architecture-5.png
+
+The proportion of Vnodes assigned to each node in a cluster is configurable in the ``num_tokens`` setting of ``scylla.yaml``; the default is ``256``.
+
+You can use the ``nodetool`` command to describe different aspects of your nodes, and the token ranges they store. For example,
+
+``$ nodetool ring <keyspace>``
+
+Outputs all tokens of a node, and displays the token ring information_. It produces output as follows for a single datacenter:
+
+.. _information: /operating-scylla/nodetool-commands/ring/
+
+.. code-block:: shell
+
+ Datacenter: datacenter1
+ =======================
+ Address Rack Status State Load Owns Token
+ 9156964624790153490
+ 172.17.0.2 rack1 Up Normal 110.52 KB 66.28% -9162506483786753398
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9154241136797732852
+ 172.17.0.4 rack1 Up Normal 118.32 KB 67.04% -9144708790311363712
+ 172.17.0.4 rack1 Up Normal 118.32 KB 67.04% -9132191441817644689
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9080806731732761568
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9017721528639019717
+ ...
+
+Here we see that, for each token, it shows the address of the node, which rack it is on, the status (``Up`` or ``Down``), the state, the load, and the token. The ``Owns`` column shows the percentage of the ring (the keyspace) actually handled by that node.
+
+``$ nodetool describering <keyspace>``
+
+Shows the token ranges of a given keyspace. That output, on a three node cluster, looks like this:
+
+.. code-block:: shell
+
+ Schema Version:082bce63-be30-3e6b-9858-4fb243ce409c
+ TokenRange:
+ TokenRange(start_token:9143256562457711404, end_token:9156964624790153490, endpoints:[172.17.0.4], rpc_endpoints:[172.17.0.4], endpoint_details:[EndpointDetails(host:172.17.0.4, datacenter:datacenter1, rack:rack1)])
+ TokenRange(start_token:9081892821497200625, end_token:9111351650740630104, endpoints:[172.17.0.4], rpc_endpoints:[172.17.0.4], endpoint_details:[EndpointDetails(host:172.17.0.4, datacenter:datacenter1, rack:rack1)])
+ ...
+
+We can also get information on our cluster with
+
+``$ nodetool describecluster``
+
+.. code-block:: shell
+
+ Cluster Information:
+ Name: Test Cluster
+ Snitch: org.apache.cassandra.locator.SimpleSnitch
+ Partitioner: org.apache.cassandra.dht.Murmur3Partitioner
+ Schema versions:
+ 082bce63-be30-3e6b-9858-4fb243ce409c: [172.17.0.2, 172.17.0.3, 172.17.0.4]
+
+Learn more in the `Cluster Node Ring lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/cluster-node-ring/>`_ on Scylla University
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/ringarchitecture/ring-architecture-1.png b/docs/architecture/ringarchitecture/ring-architecture-1.png
--- a/docs/architecture/ringarchitecture/ring-architecture-1.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-1.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-2.png b/docs/architecture/ringarchitecture/ring-architecture-2.png
--- a/docs/architecture/ringarchitecture/ring-architecture-2.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-2.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-3.png b/docs/architecture/ringarchitecture/ring-architecture-3.png
--- a/docs/architecture/ringarchitecture/ring-architecture-3.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-3.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-4.png b/docs/architecture/ringarchitecture/ring-architecture-4.png
--- a/docs/architecture/ringarchitecture/ring-architecture-4.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-4.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-5.png b/docs/architecture/ringarchitecture/ring-architecture-5.png
--- a/docs/architecture/ringarchitecture/ring-architecture-5.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-5.png
null
diff --git a/docs/architecture/sstable/_common/sstable_what_is.rst b/docs/architecture/sstable/_common/sstable_what_is.rst
--- a/docs/architecture/sstable/_common/sstable_what_is.rst
+++ b/docs/architecture/sstable/_common/sstable_what_is.rst
@@ -0,0 +1,27 @@
+:term:`Sorted Strings Table (SSTable)<SSTable>` is the persistent file format used by Scylla and Apache Cassandra. SSTable is saved as a persistent, ordered, immutable set of files on disk.
+Immutable means SSTables are never modified; they are created by a MemTable flush and are deleted by a compaction.
+The location of Scylla SSTables is specified in scylla.yaml ``data_file_directories`` parameter (default location: ``/var/lib/scylla/data``).
+
+SSTable 3.0 (mc format) is more efficient and requires less disk space than the SSTable 2.x. SSTable version support is as follows:
+
+
+.. list-table::
+ :widths: 33 33 33
+ :header-rows: 1
+
+ * - SSTable Version
+ - Scylla Enterprise Version
+ - Scylla Open Source Version
+ * - 3.x ('md')
+ - 2021.1
+ - 4.3 and above
+ * - 3.0 ('mc')
+ - 2019.1, 2020.1
+ - 3.x, 4.1, 4.2
+ * - 2.2 ('la')
+ - N/A
+ - 2.3
+ * - 2.1.8 ('ka')
+ - 2018.1
+ - 2.2
+
diff --git a/docs/architecture/sstable/index.rst b/docs/architecture/sstable/index.rst
--- a/docs/architecture/sstable/index.rst
+++ b/docs/architecture/sstable/index.rst
@@ -0,0 +1,19 @@
+Scylla SSTable Format
+=====================
+
+.. toctree::
+ :hidden:
+
+ sstable2/index
+ sstable3/index
+
+.. include:: _common/sstable_what_is.rst
+
+* In Scylla Enterprise 2021.1, Scylla 4.3 and above, *md* format is enabled by default.
+
+* In Scylla 3.1 and above, *mc* format is enabled by default.
+
+For more information on each of the SSTable formats, see below:
+
+* :doc:`SSTable 2.x <sstable2/index>`
+* :doc:`SSTable 3.x <sstable3/index>`
diff --git a/docs/architecture/sstable/sstable2/index.rst b/docs/architecture/sstable/sstable2/index.rst
--- a/docs/architecture/sstable/sstable2/index.rst
+++ b/docs/architecture/sstable/sstable2/index.rst
@@ -0,0 +1,24 @@
+Scylla SSTable - 2.x
+====================
+
+.. toctree::
+ :hidden:
+
+ sstable-compression
+ sstable-data-file
+ sstable-format
+ sstable-interpretation
+ sstable-summary-file
+
+.. include:: ../_common/sstable_what_is.rst
+
+For more information about Scylla 2.x SSTable formats, see below:
+
+
+* :doc:`SSTable Compression <sstable-compression>` - Deep dive into Scylla/Apache Cassandra SSTable Compression
+* :doc:`SSTable Data File <sstable-data-file>` - Deep dive into Scylla/Apache Cassandra SSTable format
+* :doc:`SSTable format in Scylla <sstable-format>` - Scylla SSTables are compatible to those in Apache Cassandra 2.1.8, but why there are more of them?
+* :doc:`SSTable Interpretation <sstable-interpretation>` - Deep dive into Scylla/Apache Cassandra SSTable Interpretation in Scylla
+* :doc:`SSTable Summary File <sstable-summary-file>` - Deep dive into Scylla/Apache Cassandra SSTable Summary file format
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-compression.rst b/docs/architecture/sstable/sstable2/sstable-compression.rst
--- a/docs/architecture/sstable/sstable2/sstable-compression.rst
+++ b/docs/architecture/sstable/sstable2/sstable-compression.rst
@@ -0,0 +1,100 @@
+SSTable Compression
+===================
+
+Chunked Compression of Data File
+................................
+
+SSTables compression allows to optionally compress the :doc:`SSTables Data
+File </architecture/sstable/sstable2/sstable-data-file>`, which is the biggest part of the
+SSTable (the other parts, like the index, cannot be compressed).
+
+Because random-access read from the data file is important, Apache Cassandra implements
+*chunked* compression: The uncompressed file is divided into chunks of a
+configurable fixed size (usually 64 KB), and each of these chunks is
+compressed separately and written to the compressed data file, followed
+by a 4-byte checksum of the compressed chunk. The compressed chunks have
+different lengths, so we need to remember their offsets so we can seek
+to an arbitrary chunk containing our desired uncompressed data. This
+list of offsets is stored in a separate Compression Info File, described
+below.
+
+The Compression Info File
+.........................
+
+ References: **CompressedRandomAccessReader.java**,
+ **CompressionMetadata.java**, **CompressionParameters.java**.
+
+The Compression Info File only exists if the data file is compressed.
+The Compression Info File specifies the compression parameters that the
+decompressor needs to know (such as the compression algorithm and chunk
+size), and the list of offsets of the compressed chunks in the
+compressed file:
+
+.. code:: c
+
+ struct short_string {
+ be16 length;
+ char value[length];
+ };
+
+::
+
+ struct option {
+ short_string key;
+ short_string value;
+ };
+
+::
+
+ struct compression_info {
+ short_string compressor_name;
+ be32 options_count;
+ option options[options_count];
+ be32 chunk_length;
+ be64 data_length;
+ be32 chunk_count;
+ be64 chunk_offsets[chunk_count];
+ };
+
+The **compressor\_name** can be one of three strings supported by
+Apache Cassandra: "LZ4Compressor", "SnappyCompressor" or "DeflateCompressor".
+Cassandra defaults to LZ4Compressor, but a user could choose any one of
+the three.
+
+The **options** may contain additional options for the decompressor, But
+usually no options are listed, and only one option exists:
+"crc\_check\_chance", whose value is a floating-point string which
+defaults (if the option doesn't appear) to "1.0", and determines the
+probability that we verify the checksum of a compressed chunk we read.
+
+**chunk\_length** is the length of the chunks into which the original
+uncompressed data is divided before compression. The decompressor needs
+to know this chunk size as well, so when given a desired byte offset in
+the original uncompressed file, it can determine which chunk it needs to
+uncompress. The chunk length defaults to 65536 bytes, but can be any
+power of two.
+
+**data\_length** is the total length of the uncompressed data.
+
+**chunks\_offsets** is the list of offsets of the compressed chunks
+inside the compressed file. To read data in position ``p`` in the
+uncompressed file, we calculates ``p / chunk_length`` is the
+uncompressed chunk number. The compressed version of this check is now
+begins in ``chunk_offsets[p / chunk_length]``. The compressed chunk ends
+4 bytes before the beginning of the next chunk (because, as explained
+above, every compressed chunk is followed by a 4-byte checksum).
+
+The Compressed Data File
+........................
+
+As explained above, the compressed data file is a sequence of compressed
+chunked, each a compressed version of a fixed-sized (``chunk_length``
+from the Compression Info File) uncompressed chunk. Each compressed
+chunk is followed by a be32 (big-endian 4-byte integer) Adler32 checksum
+of the *compressed* data, which can be used to verify the data hasn't
+been corrupted
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/sstable/sstable2/sstable-data-file.rst b/docs/architecture/sstable/sstable2/sstable-data-file.rst
--- a/docs/architecture/sstable/sstable2/sstable-data-file.rst
+++ b/docs/architecture/sstable/sstable2/sstable-data-file.rst
@@ -0,0 +1,263 @@
+SSTable Data File
+=================
+
+The *data file* contains a part of the actual data stored in the
+database. Basically, it is one long list of rows, where each row lists
+its key and its columns.
+
+The data file alone does not provide an efficient means to efficiently
+find a row with a specific key. For this, the ``SSTables Index File`` and
+:doc:`SSTables Summary File </architecture/sstable/sstable2/sstable-summary-file>` exist. Additionally
+the ``SSTables Bloom Filter File`` exists
+for quickly determining if a specific key exists in this SSTable
+(an Apache Cassandra table is written incrementally to several separate SSTables).
+
+The data file may be compressed as described in :doc:`SSTables
+Compression </architecture/sstable/sstable2/sstable-compression>`. As
+we explain there, the compression layer offers random access to the
+uncompressed data, like an ordinary file, so here we can assume the data
+file is uncompressed.
+
+This document explains the format of the sstable data file, but glosses
+over the question of how higher-level Apache Cassandra concepts - such as
+clustering columns, static columns, collections, etc., translate to
+sstable data. This is discussed in :doc:`SSTables
+interpretation </architecture/sstable/sstable2/sstable-interpretation>`.
+
+The Data File
+.............
+
+The data file is nothing more than a long sequence of rows:
+
+.. code:: cpp
+
+ struct data_file {
+ struct row[];
+ };
+
+The code usually skips directly to the position of a row with a desired
+key (using the index file), so we'll want an API to efficiently read
+this whole row. We'll probably (TODO: find what uses this...
+compaction?) also need an API to efficiently iterate over successive
+rows (without rereading the same disk blocks).
+
+Rows
+....
+
+ References: **SSTableIdentityIterator.java**, constructor.
+ **DeletionTime.java**
+
+Each row begins with a header which includes the row's *key*, if (and
+when) it was deleted, followed by a sequence of *cells* (column names
+and values) or other types of *atoms* described below. The last atom in
+a row is special row-end atom, marking the end of the row.
+
+.. code:: cpp
+
+ struct row {
+ be16 key_length;
+ char key[key_length];
+ struct deletion_time deletion_time;
+ struct atom atoms[];
+ };
+
+Note that the row definition does not include its length - the reader
+reads the row incrementally until reaching the row-end atom.
+Alternatively, if we want to read an entire row into memory before
+parsing it, we can figure out its length using the ``SSTables Index File``. If we
+reached this row from a particular index entry, the next index entry
+will point to the byte after the end of this row.
+
+If we reached a particular row through the index, we may already know we
+have the right key, and can skip the key at the beginning of the row
+without bothering to deserialize it.
+
+The deletion\_time structure determines whether this is a row tombstone
+- i.e., whether the whole row has been deleted, and if so, when:
+
+.. code:: c
+
+ struct deletion_time {
+ be32 local_deletion_time;
+ be64 marked_for_delete_at;
+ };
+
+The special value LIVE = (MAX\_BE32, MIN\_BE64), i.e., the bytes 7F FF
+FF 80 00 00 00 00 00 00 00, is the default for live, undeleted, rows.
+``marked_for_delete_at`` is a timestamp (typically in microseconds since
+the UNIX epoch) after which data should be considered deleted. If set to
+MIN\_BE64, the data has not been marked for deletion at all.
+``local_deletion_time`` is the local server timestamp (in *seconds*
+since the UNIX) epoch when this tombstone was created - this is only
+used for purposes of purging the tombstone after gc\_grace\_seconds have
+elapsed.
+
+Atoms (cells, end-of-row, and more)
+...................................
+
+ References: **OnDiskAtom.java**:deserializeFromSSTable(),
+ **ColumnSerializer**:deserializeColumnBody(),
+ **RangeTombstone**:deserializeBody().
+
+A row's value is a list of *atoms*, each of which is usually a cell (a
+column name and value) or an end-of-row atom, but can also be additional
+types of atoms as explained below.
+
+Each atom, of any type begins with a column name, a byte string with
+16-bit length. If the length of the name is 0 (in other words, the atom
+begins with two null bytes), this is an end-of-row atom, as the other
+atom types always have non-empty names. Note that, yes, the column names
+are repeated in each and every row. The compression layer eliminates
+much of the disk-space waste, but the overhead of parsing this verbose
+encoding remains.
+
+.. code:: cpp
+
+ struct atom {
+ be16 column_name_length;
+ char column_name[column_name_length];
+ }
+
+If the atom has a non-empty name, it is *not* an end-of-row, and
+following column\_name appears a single byte *mask*:
+
+.. code:: cpp
+
+ enum mask {
+ DELETION_MASK = 0x01,
+ EXPIRATION_MASK = 0x02,
+ COUNTER_MASK = 0x04,
+ COUNTER_UPDATE_MASK = 0x08,
+ RANGE_TOMBSTONE_MASK = 0x10,
+ };
+
+.. code:: cpp
+
+ struct nonempty_atom : atom {
+ char mask;
+ }
+
+The mask determines which type of atom this is:
+
+If mask & (RANGE\_TOMBSTONE\_MASK \| COUNTER\_MASK \| EXPIRATION\_MASK)
+== 0, we have a regular cell. This has a 64-bit timestamp (can be used
+to decide which value of a cell is most recent), and a value, serialized
+into a byte array with 32-bit length:
+
+.. code:: cpp
+
+ struct cell_atom : nonempty_atom {
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+(Note: The COUNTER\_UPDATE\_MASK and DELETION\_MASK might be turned in
+for cell\_atom, modifying its meaning).
+
+if mask & RANGE\_TOMBSTONE\_MASK, we have a
+
+.. code:: cpp
+
+ struct range_tombstone_atom : nonempty_atom {
+ u16 last_column_length;
+ char last_column_name[last_column_length];
+ struct deletion_time dt;
+ };
+
+Such a range-tombstone atom effects not just the single column
+column\_name, but the range between column\_name and last\_column\_name
+(as usual, this range is defined using the underlying comparator of the
+column name type).
+
+if mask & COUNTER\_MASK, we have a
+
+.. code:: cpp
+
+ struct counter_cell_atom : nonempty_atom {
+ be64 timestamp_of_last_delete;
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+if mask & EXPIRATION\_MASK, we have a
+
+.. code:: cpp
+
+ struct expiring_cell_atom : nonempty_atom {
+ be32 ttl;
+ be32 expiration;
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+Note that it is not valid to have more than one RANGE\_TOMBSTONE\_MASK,
+COUNTER\_MASK or EXPIRATION\_MASK on the same atom.
+
+Name and Value Serialization
+............................
+
+ References: **Composite.java**, **CompositeType.java**.
+
+It is important to remember that both column *names* and *values*
+described above are stored as a byte strings (preceded by its length,
+16-bit or 32-bit). But in Apache Cassandra, both names and values may have
+various types (as determined by the CQL schema), and those are
+**serialized** to a byte string before the byte string is serialized to
+disk as part of the atom.
+
+This has a surprising effect on the encoding of column names in the data
+file. Starting with Apache Cassandra 1.2, unless the table is created "WITH
+compact storage", column names are always *composite*, i.e., a sequence
+of components. A composite column name is serialized to a byte array
+like this:
+
+.. code:: cpp
+
+ struct serialized_composite_name {
+ struct {
+ be16 component_length;
+ char[] component; // of length component_length
+ char end_of_component; // usually 0, can be -1 (\0xff) or 1 (\0x01) - see below.
+ } component[];
+ }
+
+Then ``end_of_component`` is usually 0, but can also be -1 or 1 for
+specifying not a specific column but ranges, as explained in comments in
+Composite.java and CompositeType.java.
+
+So the surprising result is that even single-component column names
+produce wasteful double-serialization (unless the tables has WITH
+compact storage): For example, the column name "age", a composite name
+with just one component, is first serialized into ``\0 \3 a g e \0`` and
+then this serialized string is written as the column name, preceded by
+its own length, 6: ``\0 \6 \0 \3 a g e \0``.
+
+Note that the above means we need to know, when reading an sstable,
+whether column names are composite or not. Therefore the sstable reader
+need to know if this table has "WITH compact storage" or not.
+
+CQL Row Marker
+..............
+
+In some cases (namely, tables built through CQL without "WITH compact
+storage"), each row will contain a bizarre extra cell called a "CQL Row
+Marker" which the Apache Cassandra developers (who apparently don't care about
+wasting space...) added to allow a row to remain even if all its columns
+are deleted. It's worth knowing that this extra cell exists, as its
+existence might surprise the uninitiated.
+
+The "CQL Row Marker" is a normal cell in a row, which has an "empty
+composite" name and an empty value. Note that the cell's column name is
+**not** empty - it can't be (an empty name is an end-of-row marker).
+Rather, it is a composite name with one empty-string component. Such a
+composite name is serialized, as explained above, to ``\0 \0 \0`` - the
+first two null bytes are the empty component's length, and at the end we
+have the additional null added in the serialization. This
+three-null-bytes is what gets used as the column name
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-format.rst b/docs/architecture/sstable/sstable2/sstable-format.rst
--- a/docs/architecture/sstable/sstable2/sstable-format.rst
+++ b/docs/architecture/sstable/sstable2/sstable-format.rst
@@ -0,0 +1,17 @@
+SSTable format in Scylla
+========================
+
+
+Scylla supports the same SSTable format as Apache Cassandra 2.1.8, which means
+you can simply place SSTables from a Cassandra data directory into a
+Scylla data directory—and it will just work
+
+Looking more carefully, you will see that Scylla maintains more,
+smaller, SSTables than Cassandra does. On Scylla, each core manages its
+own subset of SSTables. This internal sharding allows each core (shard)
+to work more efficiently, avoiding the complexity and delays of multiple
+cores competing for the same data
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-interpretation.rst b/docs/architecture/sstable/sstable2/sstable-interpretation.rst
--- a/docs/architecture/sstable/sstable2/sstable-interpretation.rst
+++ b/docs/architecture/sstable/sstable2/sstable-interpretation.rst
@@ -0,0 +1,531 @@
+SSTable Interpretation
+======================
+
+.. role:: raw-latex(raw)
+ :format: latex
+..
+
+**Topic: Internals**
+
+**Audience: Devops professionals, architects**
+
+The SSTables Data File contains rows of data. This document discusses
+how to interpret the various fields described in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file/>` in the context of Scylla, and how to
+convert this data into Scylla's native data structure:
+**mutation\_partition**.
+
+SSTable Rows
+............
+
+Each row in the SSTable isn't necessarily a full row of data. Rather, it
+is just a **mutation**, a list of changed (added or deleted) columns and
+their new values (or "tombstone" for a deleted column), and a timestamp
+for each such change (this timestamp is used for reconciling conflicting
+mutations). The full data row needed by a request will be composed from
+potentially multiple sstables and/or the in-memory table(s).
+
+As we'll explain below when discussing clustering columns, the best term
+for what we read from one row in the SSTable isn't a "row", but rather a
+**partition**.
+
+For these reasons, Scylla's internal representation for a row we read
+from the SSTable is called ``class mutation_partition``.
+
+Column Names
+............
+
+As explained in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file>`, the
+sstable row (a mutation partition) is a list of *cells* (column values).
+Each cell is preceded by the full column name. This was considered a
+good idea when Apache Cassandra was designed to support rows with many and
+arbitrary columns, but Scylla is more oriented toward the CQL use case
+with a known schema. So Scylla's rows do not store the full column name,
+but rather store a numeric ID which points to the known list of columns
+from the schema. So as we read column names from the SSTable in form of IDs,
+we need to translate the IDs into names by looking them up in the schema.
+
+Composite Column Names
+......................
+
+But the column names mentioned in the sstable cells usually aren't a
+field name mentioned in the schema, and additional processing needs to
+be done to the column names which we read from the SSTable.
+
+The first issue is that starting with Apache Cassandra 1.2 (and unless
+``WITH COMPACT STORAGE`` is used), column names aren't plain strings,
+but each is rather rather a *composite* name - a short list of name
+components. See :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file>` for this
+list's on-disk encoding, but for simplicity of exposition let's use the
+convention of writing a composite name as **(part1:part2:...)**
+
+Things are simplest when no clustering keys are involved; Then, cell
+names have just one component. For example, consider the table created
+with the following CQL command:
+
+::
+
+ CREATE TABLE harels (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO harels (name, age) VALUES ('nadav', 40);
+
+In this table, we have a row with the key "nadav", and in this row, one
+cell, with the column name "age" encoded as a single-component composite
+string **(age)** (on disk, ``\003 a g e \0``). This only component,
+"age", can be looked up in the table's schema, and converted to a column
+ID in the ``mutation_partition``, as explained above.
+
+CQL Row Marker
+..............
+
+As explained in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file/>`,
+Apache Cassandra always (except when a COMPACT table is used and other esoteric
+exceptions) adds to each row an empty-named and empty-valued bogus
+"cell", to solve various problems involving finding a row after its only
+column has been deleted. This is also explained in a comment in
+UpdateStatement.Java, and in
+https://issues.apache.org/jira/browse/CASSANDRA-4361.
+
+For example, if we inspect with ``tools/bin/sstable2json`` the table
+created in the previous example, we find:
+
+::
+
+ {"key": "nadav",
+ "cells": [["","",1426688662900463],
+ ["age","40",1426688662900463]]}
+
+The first cell, with the empty name ("") and value (the second ""), is
+the "CQL Row Marker". As usual, the empty name "" shown by sstable2json
+is not actually an empty string, but a composite with one empty
+component, **()** (serialized on disk as ``'\000 \000 \000'``).
+
+I hope we can simply ignore these CQL Row Marker cells, and not
+duplicate them in Scylla's internal format. We just need a different way
+to allow empty rows (a row with only a key, but no data columns) to
+exist, to circumvent the problems mentioned in CASSANDRA-4361 and the
+comment in UpdateStatement.Java.
+
+Clustering Keys
+...............
+
+When the table has a clustering key, column names in the sstable no
+longer have a single component:
+
+::
+
+ USE try1;
+
+::
+
+ CREATE TABLE harels2 (
+ name text,
+ nick text,
+ age int,
+ PRIMARY KEY (name, nick)
+ ) WITH compression = {};
+
+::
+
+ INSERT INTO harels2 (name, nick, age) VALUES ('nadav', 'nyh', 40);
+
+Note how name and nick form the primary key, but the CQL syntax
+specifies that the **partition key** is name, and the **clustering key**
+is nick. This means that different tables entries that have the same
+name (but different nick) will appear in the same partition, i.e., in
+the same sstable row. Inside that partition, different nicks can appear,
+each with its own age. To see what this looks like in the sstable we
+again use the *sstable2json* tool, and see:
+
+::
+
+ {"key": "nadav",
+ "cells": [["nyh:","",1427032626839065],
+ ["nyh:age","40",1427032626839065]]}
+
+In other words, the composite column name (nyh:age) is used to store the
+age for the nick nyh, and a different column would be used to store some
+other nick's age. Note how in (nyh:age), the "nyh" is not one of the CQL
+column names, but rather the *value* of the clustering column nick, and
+only the last component, "age", is an actual name of a field from the
+CQL schema.
+
+In Scylla nomenclature, this single **partition** (with key
+name="nadav") has multiple **rows**, each with a different value of the
+clustering key (nick). Each of these rows has, as usual, columns whose
+names are the fields from the CQL schema (and as explained above, are
+kept as column IDs, not names).
+
+So when converting an sstable row into a ``mutation_partition``, we need
+to consult the schema to look for a clustering key. If "nick" is the
+clustering key, we shouldn't look as usual for cells named (nick).
+Instead, we expect *every* cell name to have >=2 components, where the
+first component is a value of nick, and the second component an actual
+column name. In the ``mutation_partition`` object, we need to insert
+multiple ``row`` objects, where each row corresponds to one value of the
+first component.
+
+The silly cell with key **(nyh:)** (empty second component) and empty
+value is the "CQL Row Marker" described above, which appears for each
+*row* (combination of partition key and clustering key) separately.
+
+Static Columns
+..............
+
+A static column is a special column which is shared by all rows of the
+same partition. As we saw above, the case of multiple rows per partition
+happens when there is a clustering column. When Datastax introduced
+static columns in Cassandra 2.0.6, they used the following example
+(http://www.datastax.com/dev/blog/cql-in-2-0-6):
+
+::
+
+ CREATE TABLE bills (
+ user text,
+ balance int static,
+ expense_id int,
+ amount int,
+ PRIMARY KEY (user, expense_id)
+ );
+
+This is a table of bills (amounts that certain users need to pay).
+According to the "PRIMARY KEY" line, the partition key is "user", and
+"expense\_id" is the clustering key; This means that there will be a
+partition (sstable row) for each user, and for each such partition, we
+can have multiple expenses (*rows*), each with a different
+clustering-key expense\_id, and corresponding amount. But the "balance"
+column is for all the different expenses of the same user.
+
+So if we insert one expense for 'user1', and set user1's balance::
+
+ INSERT INTO bills (user, balance) VALUES ('user1', 17);
+ INSERT INTO bills (user, expense_id, amount) VALUES ('user1', 1, 8);
+
+What is written to the sstable looks like this (as usual, output from
+``sstable2json``):
+
+::
+
+ {"key": "user1",
+ "cells": [[":balance","17",1428849747953348],
+ ["1:","",1428849747970947],
+ ["1:amount","8",1428849747970947]]}
+
+The (1:amount) and (1:) is what we already saw above, the new thing here
+is the (:balance), a static column.
+
+So sstables have static columns specially marked by an empty first
+component of the composite cell name. We need to verify that each such
+cell actually corresponds to a known static column from the table's
+schema, and collect all these static columns into one row
+(``_static_row``) stored in Scylla's ``mutation_partition``.
+
+TODO: CompositeType.java explains that static columns do not really have
+an empty first component (size 0), but rather the first component has
+the fake size STATIC\_MARKER = 0xFFFF (65536). We need to verify this.
+
+Compound Clustering Key
+.......................
+
+When the clustering key is compound, i.e., composed of multiple columns,
+the SSTable column names will contain more than two components. For
+example consider:
+
+::
+
+ USE try1;
+ CREATE TABLE bills3 (
+ user text,
+ expense_id int,
+ year int,
+ amount int,
+ PRIMARY KEY (user, year, expense_id)
+ );
+
+::
+
+ INSERT INTO bills3 (user, year, expense_id, amount) VALUES ('user1', 2015, 1, 8);
+
+Here as usual, the first column name in "PRIMARY KEY", user, is the
+partition key, but the two others, year and expense\_id are both
+clustering columns, forming a compound clustering key. I.e., each
+partition contains several rows, each defined by (and sorted by) the
+pair (year, expense\_id).
+
+The resulting SSTable row is:
+
+::
+
+ {"key": "user1",
+ "cells": [["2015:1:","",1428853746711253],
+ ["2015:1:amount","8",1428853746711253]]}
+
+Note how the column name "amount" is now prefixed by two components, the
+values of the two clustering columns. Of course, a schema can have any
+number of clustering columns and as a result, expect that number of
+prefix components in the SSTable's column names.
+
+As before, all but the last column-name component are expected to be
+values of the clustering-key of the various rows inside the partition,
+and only the last component is a column name to be looked up in the
+schema. It's safer, though, to consult with the schema to see the number
+of clustering columns instead of guessing it as the number of components
+minus one. This is a good sanity check, and also necessary when
+collections are concerned (see below).
+
+Compound Partition Key
+......................
+
+The row key read from the SSTable can also be a composite (a list of
+components) if the schema says the partition key is compound. For
+example:
+
+::
+
+ CREATE TABLE bills2 (
+ user text,
+ expense_id int,
+ amount int,
+ PRIMARY KEY ((user, expense_id))
+ );
+ INSERT INTO bills (user, expense_id, amount) VALUES ('user1', 1, 8);
+
+Note the extra pair of parenthesis in the "PRIMARY KEY" specification,
+which says that expense\_id is part of the partition key, not a
+clustering ey.
+
+The key of each SSTable row is now the pair (user, expense\_id), a
+composite with two components.
+
+TODO: Print the resulting SSTable
+
+Collections
+...........
+
+The encoding of *collections* in SSTables is more complex.
+
+Consider this table definition with a column which is a *set*
+collection:
+
+::
+
+ CREATE TABLE col2 (
+ user text,
+ favorites set<text>,
+ PRIMARY KEY (user)
+ );
+
+::
+
+ INSERT INTO col2 (user, favorites) VALUES ('user1', {'raindrops', 'kittens'});
+
+The resulting SSTable row is:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428855312063525],
+ ["favorites:_","favorites:!",1428855312063524,"t",1428855312],
+ ["favorites:6b697474656e73","",1428855312063525],
+ ["favorites:7261696e64726f7073","",1428855312063525]]}
+
+Here we also have two components in the column names, but we need to
+know this is not the case of a clustering key ("favorites" isn't a value
+of a clustering column) but that of a collection. We need to consult the
+schema to tell the two cases apart (in this case, there are no
+clustering columns, so no component needs to be treated as a clustering
+column, so when we see two components, it must be a collection).
+
+In a set, we have a cell for each item in the collection, and *second*
+component of the cell's name is the serialized value. E.g., in our case,
+the byte array "kittens" is shown by sstable2json in hex
+(6b697474656e73) - in the actual SSTable the hex does not appear (there
+is the length of the string followed by the actual bytes). The value of
+each of these cells is empty for a *set* (for other types of collections
+it is not empty - see below).
+
+The weird cell in the beginning of the above sstable2json output (with
+``favorites:_``) is not a normal cell - this is how sstable prints a
+*range tombstone*, whose range is between the start of "favorites:" and
+the end of "favorites:", the markedForDeleteAt value is 1428855312063524
+and localDeletionTime is 1428855312. The need for this range tombstone
+appears to be as follows: Because each of the collection's items is a
+separate cell, when we *set* the collection (as in the INSERT command we
+used) the intention is to delete any old item in the collection, if
+there are any, and add the new items. The range tombstone takes care of
+deleting all the old items.
+
+The actual sstable doesn't have the "\_" or "!" characters printed by
+sstable2json. What it really has is ``"\00\09favorites\ff"`` and
+:raw-latex:`\0`0:raw-latex:`\0`9favorites:raw-latex:`\0`1". I.e., each
+of these two column names has only one component, but instead of ending
+as usual with the end-of-component byte :raw-latex:`\0`0, the first ends
+with :raw-latex:`\ff `(START) and the second ends with :raw-latex:`\0`1
+(END). This means the range tombstone spans everything between the first
+column and the last, as indeed desired.
+
+The second type of collection, the **map**, is similar to the **set**,
+just the value is not empty but rather the desired value in the map. For
+example,
+
+::
+
+ CREATE TABLE col4 (
+ user text,
+ favorites map<text,int>,
+ PRIMARY KEY (user)
+ ) WITH compression = {};
+ INSERT INTO col4 (user, favorites) VALUES ('user1', {'raindrops' : 1, 'kittens' : 2});
+
+We see in the SSTable with sstable2json:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428864848550739],
+ ["favorites:_","favorites:!",1428864848550738,"t",1428864848],
+ ["favorites:6b697474656e73","00000002",1428864848550739],
+ ["favorites:7261696e64726f7073","00000001",1428864848550739]]}
+
+I.e., indeed exactly the same as the representation of the set, except
+the cell's values are the desired 1 and 2. The way the values are
+printed above as strings ("0000002") is just an artifact of how
+sstable2json works - the value is represented in the SSTable as an
+actual serialized int (32-bit length 4, followed by 4 bytes of the
+integer's representation) as expected.
+
+For the ordered **list** collection, things are similar, but not quite
+the same because of the need to keep the desired item order:
+
+::
+
+ CREATE TABLE col1 (
+ user text,
+ favorites list<text>,
+ PRIMARY KEY (user)
+ );
+ INSERT INTO col1 (user, favorites) VALUES ('user1', ['raindrops', 'kittens']);
+
+The resulting SSTable row is now:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428854738475900],
+ ["favorites:_","favorites:!",1428854738475899,"t",1428854738],
+ ["favorites:c2bcd290e12d11e49cac000000000000","7261696e64726f7073",1428854738475900],
+ ["favorites:c2bcd291e12d11e49cac000000000000","6b697474656e73",1428854738475900]]}
+
+Note how this time, the items ("raindrops" and "kittens") are the value
+of the cell, not in the column name. In the column name we have some
+long strings intended to sort in the requested list order. These long
+hex strings are misrepresented by sstable2json - they are not a hex
+string but rather a 16-byte UUID.
+
+To merely keep the list items in order, Apache Cassandra could have used small
+integers instead of these UUIDs. But these UUIDs have an additional
+benefit: as http://www.datastax.com/dev/blog/cql3\_collections explains,
+Apache Cassandra wishes to allow efficient *append* and *prepend* operations to
+an existing list - without reading the existing list first (i.e., the
+append/prepend is a fast write-only mutation, not a slow
+read-modify-write operation). To achieve that, Apache Cassandra uses signed
+time-UUIDs as the list sort string - with positive times used for append
+operations, and negative for prepend operations. This ensures that, for
+example, a later append always sorts after an earlier append - without
+the append having to know which items already exist in the list.
+
+Scylla's internal storage of a collection in a mutation is the
+``class collection_mutation``, and we need to convert the above
+described representation into that class. TODO: I still can't figure out
+exactly what is the internal structure of our collection\_mutation
+(which hides behind an opaque byte array), or what functions we are
+supposed to call to build one).
+
+Cells with Expiration Time
+..........................
+
+An SSTable cell may have an expiration time, as explained
+http://docs.datastax.com/en/cql/3.1/cql/cql\_using/use\_expire\_c.html.
+Such a cell is marked by the EXPIRATION\_MASK bit in the mask byte, and
+in addition to the cell's normal fields, has two additional fields,
+"ttl" and "expiration", both 32-bit and measured in seconds. "ttl" is
+the original time-to-live (number of seconds until expiration) specified
+when the cell was created, and "expiration" is the absolute time when
+the cell should be expired (in seconds since the Unix Epoch).
+
+The following CQL example creates a cell with a time-to-live of 3600
+seconds:
+
+::
+
+ CREATE TABLE ttl (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO ttl (name, age) VALUES ('nadav', 40) USING TTL 3600;
+
+sstable2json prints the resulting SSTable row as:
+
+::
+
+ {"key": "nadav",
+ "cells": [["","",1430151018675502,"e",3600,1430154618],
+ ["age","40",1430151018675502,"e",3600,1430154618]]}
+
+Note how each of cells (the cql row marker, and our actual data cell)
+have a TTL of 3600 seconds, and an expiration time calculated by adding
+3600 to the current time on the server. The fact that the row marker
+also got this TTL is not certain to be a good thing - see discussion in
+https://issues.apache.org/jira/browse/CASSANDRA-5762.
+
+Cell Tombstone
+..............
+
+We've already discussed row tombstones (marking the deletion of an
+entire row) and range tombstone (marking the deletion of a range of
+columns). We can also have a cell tombstone, marking the deletion of a
+single cell. A deleted cell is encoded in the SSTable like a normal
+cell, except the mask has the DELETION\_MASK bit, and the *value* of the
+cell contains the serialized ``local_deletion_time`` (the local server
+time in seconds since the epoch), which is probably only needed for the
+purpose of purging the tombstone after gc\_grace\_seconds have elapsed.
+
+To create an sstable with a deleted cell in Apache Cassandra, consider creating
+a table with some data:
+
+::
+
+ CREATE TABLE deleted (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO deleted (name, age) VALUES ('nadav', 40);
+
+Then flushing this data to an SSTable (with
+``bin/nodetool flush keyspacename``), and then deleting the cell we
+added:
+
+::
+
+ DELETE age FROM deleted WHERE name = 'nadav';
+
+When the second SSTable is flushed, it will have a cell tombstone.
+sstable2json shows the second SSTable like this:
+
+::
+
+ {"key": "nadav",
+ "cells": [["age",1430200516,1430200516937621,"d"]]}
+
+Note how the cell has the DELETION\_MASK bit (written as a "d"), its
+"value" is the local-deletion-time, 1430200516, and as usual it has a
+timestamp
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/sstable/sstable2/sstable-summary-file.rst b/docs/architecture/sstable/sstable2/sstable-summary-file.rst
--- a/docs/architecture/sstable/sstable2/sstable-summary-file.rst
+++ b/docs/architecture/sstable/sstable2/sstable-summary-file.rst
@@ -0,0 +1,37 @@
+SSTable Summary File
+====================
+
+SSTable Summary file format
+
+.. code:: c
+
+ struct summary_entry {
+ char key[...]; // variable-length.
+ be64 position;
+ };
+
+.. code:: c
+
+ struct summary_la {
+ struct header {
+ be32 min_index_interval;
+ be32 size;
+ be64 memory_size;
+ be32 sampling_level;
+ be32 size_at_full_sampling;
+ } header;
+
+::
+
+ le32 positions[header.size];
+ summary_entry entries[header.size];
+
+ be32 first_key_size;
+ char first_key[first_key_size];
+
+ be32 last_key_size;
+ char last_key[last_key_size];
+ };
+
+.. include:: /rst_include/architecture-index.rst
+
diff --git a/docs/architecture/sstable/sstable3/index.rst b/docs/architecture/sstable/sstable3/index.rst
--- a/docs/architecture/sstable/sstable3/index.rst
+++ b/docs/architecture/sstable/sstable3/index.rst
@@ -0,0 +1,32 @@
+Scylla SSTable - 3.x
+====================
+
+.. toctree::
+ :hidden:
+
+ sstables-3-data-file-format
+ sstables-3-statistics
+ sstables-3-summary
+ sstables-3-index
+ sstable-format
+
+.. include:: ../_common/sstable_what_is.rst
+
+* In Scylla 3.1 and above, mc format is enabled by default.
+
+* In Scylla 3.0, mc format is disabled by default and can be enabled by adding the ``enable_sstables_mc_format`` parameter as 'true' in ``scylla.yaml`` file.
+
+For example:
+
+.. code-block:: shell
+
+ enable_sstables_mc_format: true
+
+
+For more information on Scylla 3.x SSTable formats, see below:
+
+* :doc:`SSTable 3.0 Data File Format <sstables-3-data-file-format>`
+* :doc:`SSTable 3.0 Statistics <sstables-3-statistics>`
+* :doc:`SSTable 3.0 Summary <sstables-3-summary>`
+* :doc:`SSTable 3.0 Index <sstables-3-index>`
+* :doc:`SSTable 3.0 Format in Scylla <sstable-format>`
diff --git a/docs/architecture/sstable/sstable3/sstable-format.rst b/docs/architecture/sstable/sstable3/sstable-format.rst
--- a/docs/architecture/sstable/sstable3/sstable-format.rst
+++ b/docs/architecture/sstable/sstable3/sstable-format.rst
@@ -0,0 +1,16 @@
+SSTable 3.0 Format in Scylla
+============================
+
+Scylla supports the same SSTable format as Apache Cassandra 3.0.
+You can simply place SSTables from a Cassandra data directory into a Scylla uploads directory
+and use the ``nodetool refresh`` command to ingest their data into the table.
+
+Looking more carefully, you will see that Scylla maintains more,
+smaller, SSTables than Cassandra does. On Scylla, each core manages its
+own subset of SSTables. This internal sharding allows each core (shard)
+to work more efficiently, avoiding the complexity and delays of multiple
+cores competing for the same data
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst b/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
@@ -0,0 +1,555 @@
+SSTables 3.0 Data File Format
+=============================
+
+.. versionadded:: 3.0
+
+This article aims at describing the format of data files introduced in Cassandra 3.0. The data file is the file that actually stores the data managed by the database. As important as it is, this file does not come alone. There are other files that altogether constitute a set of components sufficient for manipulating the stored data.
+The following table outlines the types of files used by Cassandra SSTables 3.0:
+
+============================================================ =========================== =======================================================================================
+File Type Typical Name Description
+============================================================ =========================== =======================================================================================
+Compression information mc-1-big-CompressionInfo.db Contains information about the compression algorithm, if used
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Data file mc-1-big-Data.db Stores the actual data
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Checksum file mc-1-big-Digest.crc32 Contains a checksum of the data file
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Bloom filter mc-1-big-Filter.db Contains a Bloom filter to check whether particular data may be stored in the data file
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Index mc-1-big-Index.db Contains the primary index of data for easier search
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Statistics mc-1-big-Statistics.db Stores aggregated statistics about the data
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Summary mc-1-big-Summary.db Provides sampling of the index file (can be seen as "coarse-grained" index)
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Table of contents mc-1-big-TOC.txt Lists all the files for the current SSTable
+============================================================ =========================== =======================================================================================
+
+This document focuses on the data file format but also refers to other components in parts where information stored in them affects the way we read/write the data file.
+
+Note that the file on-disk format applies both to the "mc" and "md" SSTable format versions.
+The "md" format only fixed the semantics of the (min|max)_clustering_key fields in the SSTable Statistics file, which are now valid for describing the accurate range of clustering prefixes present in the SSTable.
+See `SSTables 3.0 Statistics File Format <architecture/sstable/sstable3/sstables-3-statistics/>`_ for more details.
+
+Overview
+........
+
+The storage format has been significantly revamped in Cassandra 3.0 compared to the 2.x series. The primary driver for that was the fact that the previous storage format has been devised long before CQL and did not reflect its concepts and abstractions. This, in turn, hindered various fixes and led to suboptimal disk space usage.
+
+To understand what that means, you can refer to the :doc:`SSTables 2.x data file format </architecture/sstable/sstable2/sstable-data-file>` description. In brief, in 2.x every data file is a sequence of partitions (called "rows" in pre-CQL terminology) where each partition is more or less a sequence of cells (or, more precisely, atoms with a majority of them being cells). There is no notion of columns or rows (in CQL terminology) at this level. Each cell has its full name comprised of the clustering prefix (values of all the clustering columns) followed by the non-PK column name.
+
+This scheme causes a lot of duplication since for every row in a given partition determined by a set of clustering columns values those values are stored in names of all the cells that belong to this row. For composite primary keys with long clustering columns values that would mean a lot of disk space wasted for no good reason. Another consequence is that the storage engine has to recognize and group cells from the row itself without knowing in advance their count or overall size.
+
+SSTables 3.0 format addresses this by re-arranging the way data is stored. Now every partition is comprised of rows. Each row is defined by its clustering columns values and consists of a number of cells that all share those clustering columns values as their name prefix. So now one can reason about the data file as a sequence of partitions where partition consists of rows that consist of cells, whereas before it was a sequence of partitions with each partition consisting of cells. This is oversimplified but helpful for understanding the high-level picture of changes.
+
+SSTables 3.0 data file format relies heavily on the table schema. It contains information about PK and non-PK columns, corresponding data types and width (fixed-width vs. variable-width), clustering columns ordering and so on.
+
+Let's examine in more detail how the data representation looks in 3.0.
+
+.. _sstables-3-building-blocks:
+
+Building Blocks
+...............
+
+Before we describe the data format in every detail, let's define a few concepts that are used throughout the whole SSTables 3.0 specification. They act as building blocks for the new format and are responsible for noticeable space savings compared to the old one.
+
+Variable Length Integers (Varints)
+----------------------------------
+
+Variable length integers are inspired by Google Protocol Buffers internal representation for serialised integers. They can save a significant amount of memory/space if the majority of serialised integer values are relatively small.
+
+The internal representation of varints is explained in great detail in this `article`_.
+The main idea is that variable-length integers occupy between 1 and 9 bytes and smaller values require fewer bytes so the format is efficient for storing many relatively small values.
+
+.. _article: https://haaawk.github.io/2018/02/26/sstables-variant-integers.html
+
+In the structures below, `varint` will indicate an integer stored in its variable-length representation on the disk according to the described encoding.
+
+Delta Encoding
+--------------
+
+A lot of values stored in a data file represent timestamps or TTL which values are microseconds since UNIX epoch. Those values are quite large and as such don't benefit much from being stored as varints. The idea that allows reducing timestamp/TTL values footprint is to only store the full value of the minimal timestamp/TTL per a set of objects. For other objects that have a different timestamp/TTL, we store its delta from the minimal value. The delta is typically much smaller and thus has a better chance to occupy fewer bytes upon serialisation.
+Varints can be used for storing deltas just fine.
+
+Optional Items
+--------------
+
+In order to save more disk space, some items can be omitted during serialisation. The presence or absence of a particular optional item is typically indicated by a flag or, in some cases, can be easily deduced in some way from the preceding data.
+These items are marked as optional below. Keep in mind this is **not** `optional`_ but rather merely a convention to mark the items that may not be present in a particular data file.
+
+.. _`optional`: http://en.cppreference.com/w/cpp/utility/optional
+
+The Data File Layout
+....................
+
+The data file itself, just as before, is no more than a plain sequence of serialised partitions:
+
+.. code:: cpp
+
+ struct data_file {
+ struct partition[];
+ };
+
+Partition
+---------
+
+References:
+
+* `Clusterable.java`_
+
+.. _`Clusterable.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Clusterable.java/
+
+* `ClusteringPrefix`_
+
+.. _`ClusteringPrefix`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ClusteringPrefix.java/
+
+* `ClusteringComparator`_
+
+.. _`ClusteringComparator`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ClusteringComparator.java/
+
+* `Unfiltered.java`_
+
+.. _`Unfiltered.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/Unfiltered.java/
+
+When talking about partitions in SSTables, one needs to keep in mind that those partitions contain information about the updates to data and **not** the final state of data. That is, every partition in SSTables is a collection of records (commonly referred to as **mutations**) that have been applied sequentially to modify (insert, update or delete) the data in the data partition with a given partition key.
+
+A partition consists of a header, an optional static row and a sequence of clusterable objects:
+
+.. code:: cpp
+
+ struct partition {
+ struct partition_header header;
+ optional<struct row> static_row; // Has IS_STATIC flag set
+ struct unfiltered unfiltereds[];
+ };
+
+
+The ``partition_header`` contains partition key and deletion information, just as in 2.x formats.
+
+The optional ``static_row`` is only present if there have been inserts to the table's static column(s). If no inserts are present in the Memtable that is flushed into the SSTable, the static row is not present even though the table schema may contain static columns. Static row structure is given below, for now, it suffices to say that it only differs from regular (non-static) rows in that it doesn't have a clustering prefix.
+
+An unfiltered object is an object that can be ordered by the clustering prefix using a ``clustering_comparator`` according to its clustering values and the schema-induced ordering.
+
+.. code:: cpp
+
+ struct unfiltered {
+ };
+
+
+Any unfiltered data in a partition is either a row or a ``range_tombstone_marker``. We will examine both of them below.
+
+Partition Header
+----------------
+
+Reference:
+
+`ColumnIndex.java, writePartitionHeader`_
+
+.. _`ColumnIndex.java, writePartitionHeader`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ColumnIndex.java/
+
+The `partition_header` format has not changed since 2.x and is defined as:
+
+.. code:: cpp
+
+ struct partition_header {
+ be16 key_length;
+ byte key[key_length];
+ struct deletion_time deletion_time;
+ };
+
+The ``deletion_time`` structure determines whether this is a partition tombstone - i.e., whether the whole partition has been deleted, and if so, when:
+
+.. code:: cpp
+
+ struct deletion_time {
+ be32 local_deletion_time;
+ be64 marked_for_delete_at;
+ };
+
+The special value LIVE = (MAX_BE32, MIN_BE64), i.e., the bytes `7F FF FF FF 80 00 00 00 00 00 00 00`, is the default for live, undeleted, partitions. ``marked_for_delete_at`` is a timestamp (typically in microseconds since the UNIX epoch) after which data should be considered deleted. If set to MIN_BE64, the data has not been marked for deletion at all. ``local_deletion_time`` is the local server timestamp (in seconds since the UNIX) epoch when this tombstone was created - this is only used for purposes of purging the tombstone after ``gc_grace_seconds`` have elapsed.
+
+Row
+---
+
+References:
+
+`UnfilteredSerializer.java, serialize`_
+
+.. _`UnfilteredSerializer.java, serialize`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/UnfilteredSerializer.java#L125/
+
+A `row` is represented with the following layout:
+
+.. code:: cpp
+
+ struct row {
+ byte flags;
+ optional<byte> extended_flags;
+ // only present for non-static rows
+ optional<struct clustering_block[]> clustering_blocks;
+ varint row_body_size;
+ varint prev_unfiltered_size; // for backward traversing
+ optional<struct liveness_info> liveness_info;
+ optional<struct delta_deletion_time> deletion_time;
+ optional<varint[]> missing_columns;
+ cell[] cells;
+ };
+
+Row Flags
+---------
+
+The first byte `flags` is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class row_flags {
+ // Signal the end of the partition. Nothing follows a <flags> field with that flag.
+ END_OF_PARTITION = 0x01,
+ // Whether the encoded unfiltered is a marker or a row. All following flags apply only to rows.
+ IS_MARKER = 0x02,
+ // Whether the encoded row has a timestamp (i.e. its liveness_info is not empty).
+ HAS_TIMESTAMP = 0x04,
+ // Whether the encoded row has some expiration info (i.e. if its liveness_info contains TTL and local_deletion).
+ HAS_TTL = 0x08,
+ // Whether the encoded row has some deletion info.
+ HAS_DELETION = 0x10,
+ // Whether the encoded row has all of the columns from the header present.
+ HAS_ALL_COLUMNS = 0x20,
+ // Whether the encoded row has some complex deletion for at least one of its complex columns.
+ HAS_COMPLEX_DELETION = 0x40,
+ // If present, another byte is read containing the "extended flags" below.
+ EXTENSION_FLAG = 0x80
+ };
+
+
+If `EXTENSION_FLAG` is set, the following byte `extended_flags` is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class row_extended_flags {
+ // Whether the encoded row is a static. If there is no extended flag, the row is assumed not static.
+ IS_STATIC = 0x01,
+ // Whether the row deletion is shadowable. If there is no extended flag (or no row deletion), the deletion is assumed not shadowable. This flag is deprecated - see CASSANDRA-11500.
+ // This flag is not supported by Scylla and SSTables that have this flag set fail to be loaded.
+ HAS_SHADOWABLE_DELETION_CASSANDRA = 0x02,
+ // A Scylla-specific flag (not supported by Cassandra) that indicates the presence of a shadowable tombstone.
+ // See below for details
+ HAS_SHADOWABLE_DELETION_SCYLLA = 0x80,
+ };
+
+As mentioned earlier, every partition may or may not have a static row. If present, the static row precedes any other rows or range tombstone markers and has ``EXTENSION_FLAG`` set in ``flags`` and ``IS_STATIC`` set in ``extended_flags``. As you might expect, the static row will not have any clustering information just by its definition.
+
+Clustering Blocks
+-----------------
+
+If ``IS_STATIC`` is not set or ``extended_flags`` byte is missing, the row has a list of clustering blocks that represents the values of clustering columns.
+
+.. code:: cpp
+
+ struct clustering_block {
+ varint clustering_block_header;
+ simple_cell[] clustering_cells;
+ };
+
+
+To build the clustering blocks, all the clustering columns are split into batches of 32 (or less for the last batch).
+To calculate the ``clustering_block_header``, for each column in batch, the information about if its cell is null or empty is encoded using 2 bits in a 64-bit integer. The higher bit is set if the cell value is null or the smaller set if it is empty.
+A ``null`` cell means that this column doesn't have a value in the current row. An empty cell means that the value exists but is empty in a way (e.g., if the data type is ``text`` or `blob`, this indicates it has no bytes and a zero length in it). Note that for rows, clustering cells are never ``null``. But this encoding is also used for range tombstone markers that can contain only a prefix of clustering cells with others being treated as ``null`` in this case.
+The number of clustering blocks is not stored in the data file as it can be easily deduced from the schema.
+
+The resulting integer is then stored as ``varint clustering_block_header``. Next, the cells from the current batch are serialised using simple cells serialisation which is described below.
+
+Note that we don't store the number of clustering cells as we take this information from table schema.
+
+Sizes
+-----
+
+After the clustering blocks, the size of the serialised row is calculated and stored as a `varint`. This is the number of bytes between the byte after the last clustering block (inclusive) and the `flags` byte of the next `unfiltered` (exclusive) or the end of the file.
+
+Next `varint` is the size of the previous unfiltered (not necessarily a row, can be a range tombstone marker), supposedly stored to allow backwards traversal.
+
+Row Content
+-----------
+
+After the sizes, next goes the ``liveness_info`` which is defined as:
+
+.. code:: cpp
+
+ struct liveness_info {
+ varint delta_timestamp;
+ optional<varint> delta_ttl;
+ optional<varint> delta_local_deletion_time;
+ };
+
+
+It is present if ``HAS_TIMESTAMP`` flag is set. This liveness information is what allows us to distinguish between a dead row (it has no live cells and its primary key liveness info is empty) and a live row but where all non-PK columns are null (it has no live cells, but its primary key liveness is not empty). Please note that the liveness info only applies to the primary key columns and has no impact on the row content.
+In a way, ``liveness_info`` is a less hacky successor to CQL row marker used in 2.x data format.
+
+In liveness_info, as well as in some other places, timestamps, TTLs and deletion time values are stored as `varint`s using delta encoding. But an astute reader may ask a reasonable question: "What are the base values these deltas are taken from?". It turns out that a Memtable maintains aggregated statistics about all the information put into it and tracks the minimal timestamp, TTL and local deletion time values across all the records. These values are used as bases for delta encoding when the Memtable is flushed onto the disk. The values themselves are stored in `-Statistics.db` file and deserialised from there before the data file is read. For more details, refer to `EncodingStats.java`_ and `Memtable.java`_,
+
+.. _`EncodingStats.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/EncodingStats.java
+
+.. _`Memtable.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Memtable.java#L232
+
+
+If the TTL information was included in the modification statement, the ``HAS_TTL`` flag is set. In this case, both TTL and local deletion time values are stored as ``varints`` using deltas taken from the corresponding minimal values from Memtable stats.
+
+For dead row markers or expired liveness info, a special value -1 of TTL is set.
+
+If the row is deleted, `HAS_DELETION` flag is set. In this case, ``deletion_time`` is delta-encoded as follows:
+
+.. code:: cpp
+
+ struct delta_deletion_time {
+ varint delta_marked_for_delete_at;
+ varint delta_local_deletion_time;
+ };
+
+
+Note that the order here is different from partition header: in ``partition_header``, ``local_deletion_time`` is serialised first and then followed by ``marked_for_delete_at``. Here, delta-encoded ``marked_for_delete_at`` precedes delta-encoded ``local_deletion_time``.
+
+Shadowable Tombstones
+---------------------
+
+Cassandra only maintains up to one tombstone for a row. In case if it is shadowable, Cassandra sets the corresponding HAS_SHADOWABLE_DELETION_CASSANDRA flag.
+
+It turns out that this approach is imperfect and there are known issues with the current shadowable deletions support in Cassandra (see https://issues.apache.org/jira/browse/CASSANDRA-13826 for details).
+To address those, Scylla maintains a separate shadowable tombstone in addition to the regular one. That means a row can have up to two tombstones in Scylla-written SSTables. If the second tombstone is present, the Scylla-specific extended flag HAS_SHADOWABLE_DELETION_SCYLLA is set.
+
+Note that Cassandra does not know this flag and would consider those files invalid. This is deemed to be safe to do because shadowable tombstones can only appear in Materialized Views tables and those are not supposed to be ever exported and imported between Scylla and Cassandra.
+
+Missing Columns Encoding
+------------------------
+
+Reference:
+
+`Columns.java, serializeSubset`_
+
+.. _`Columns.java, serializeSubset`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Columns.java#L444
+
+
+Next, if `HAS_ALL_COLUMNS` flag is **not** set, the `missing_columns` field contains information about which columns are _missing_. Note that the `HAS_ALL_COLUMNS` flag doesn't necessarily mean that the row has all the columns from the table schema definition. Each Memtable keeps track of filled columns on updates so when serialised into SSTables, the columns of a particular row are compared against the superset of filled columns in the Memtable. For example, if your table has 5 non-clustering columns ('a' through 'e'), all the records in the current Memtable have only some of ('a', 'b', 'c') filled and the current row has all 'a', 'b' and 'c', it will have the `HAS_ALL_COLUMNS` flag set even though it doesn't have columns 'd' and 'e'. This information (the list of all filled columns) is also stored in `-Statistics.db`.
+
+We have a _superset_ of columns, which is a list of all non-PK columns in the table, and a _current set of columns, which is a list of columns filled within this row. The encoding procedure is optimised towards small column sets (<64 columns) and employs slightly more complex encoding for larger sets.
+When the superset columns count is < 64, a 64-bit integer is used as a bitmap with its bits set for **missing** columns and stored as a single `varint`.
+
+For larger supersets, the delta between the superset columns count and the current row columns count is written as the first `varint`.
+The procedure then differs based on whether the number of columns in the row is less than half of the size of the superset or not.
+If `columns.count() < superset.count() / 2`, the **present** columns indices are written as `varints`, otherwise the **missing** columns indices are written. The logic is clear - we just write whatever appears to be less in count.
+
+Although the field is named `missing_columns`, one can see from the algorithm described above that in some cases the values stored are indices of present columns, not missing ones. This may be a bit confusing, but it helps to reason about it in the following way: whatever is stored can be used to get the list of missing columns.
+
+As of today, Scylla treats the whole set of columns as a superset regardless of whether all columns are ever filled or not. `See for details`_.
+
+.. _`See for details`: https://github.com/scylladb/scylla/issues/3901
+
+Lastly, all the cells of the current row are encoded.
+
+Cells
+-----
+
+References:
+
+* `BufferCell.java, Serializer.serialize`_
+
+* `UnfilteredSerializer, writeComplexColumn`_
+
+.. _`BufferCell.java, Serializer.serialize`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/BufferCell.java#L236
+
+.. _`UnfilteredSerializer, writeComplexColumn`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/UnfilteredSerializer.java#L204
+
+
+.. code:: cpp
+
+ struct cell {
+ };
+
+
+Any non-clustering column can be either "simple", which means it can only have a single cell associated to it in any row, or "complex", where an arbitrary number of cells can be associated. As of today, "complex" columns are those declared for non-frozen collections. All clustering columns are "simple" because non-frozen collections are allowed for non-PK columns only - if you remember, we said earlier that the cells in a clustering block are serialised using `simple_cell` serialisation.
+> Note that since we encode the information about filled columns, every cell is non-null by definition. They can still be empty though.
+
+A cell is recognised as simple or complex based the definition in the table schema for the column that owns this cell.
+
+Simple Cells
+------------
+
+A serialised simple sell looks like:
+
+.. code:: cpp
+
+ struct simple_cell
+ : cell {
+ byte flags;
+ optional<varint> delta_timestamp;
+ optional<varint> delta_local_deletion_time;
+ optional<varint> delta_ttl;
+ optional<cell_path> path; // only in cells nested into complex_cells
+ optional<struct cell_value> value;
+ };
+
+First, the `flags` byte is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class cell_flags {
+ IS_DELETED_MASK = 0x01, // Whether the cell is a tombstone or not.
+ IS_EXPIRING_MASK = 0x02, // Whether the cell is expiring.
+ HAS_EMPTY_VALUE_MASK = 0x04, // Whether the cell has an empty value. This will be the case for a tombstone in particular.
+ USE_ROW_TIMESTAMP_MASK = 0x08, // Whether the cell has the same timestamp as the row this is a cell of.
+ USE_ROW_TTL_MASK = 0x10, // Whether the cell has the same TTL as the row this is a cell of.
+ };
+
+
+`IS_DELETED_MASK` and `IS_EXPIRING_MASK` flags are mutually exclusive for an obvious reason that the same cell can either be deleted or live but expiring.
+
+If `USE_ROW_TIMESTAMP_MASK` flag is **not** set, i.e., the cell timestamp differs from that of the row, the delta-encoded timestamp is stored as a `varint`.
+
+If the cell is a tombstone (`IS_DELETED_MASK` is set) or expiring (`IS_EXPIRING_MASK` is set) and its local deletion time and TTL differ from those of the row (`USE_ROW_TTL_MASK` is **not** set), cell delta-encoded local deletion time is stored as a `varint`.
+
+If the cell is expiring (`IS_EXPIRING_MASK` is set) and its TTL differs from that of the row (`USE_ROW_TTL_MASK` is **not** set), cell delta-encoded TTL is stored as a `varint`.
+
+A regular simple cell that belongs to a simple column doesn't have a `path` item. This one only appears in cells wrapped by a `complex_cell` (see below).
+
+Finally, if the cell value is not empty (`HAS_EMPTY_VALUE_MASK` is **not** set), it is serialised. It can be a fixed-width value (for fixed-width CQL data types like `int` or `boolean`) or a variable-width one (for CQL data types like `text` or `blob`). Those are encoded differently since we don't need to store the length of fixed-width values (it can be deduced from the table schema definition) but have to for variable-length cells.
+
+.. code:: cpp
+
+ struct cell_value {
+ optional<varint> length;
+ byte value[];
+ };
+
+
+Complex Cells
+-------------
+
+A complex cell acts as a kind of a container for multiple simple cells distinguished by so-called `cell_path`:
+
+.. code:: cpp
+
+ struct complex_cell
+ : cell {
+ optional<struct delta_deletion_time> complex_deletion_time;
+ varint items_count;
+ struct simple_cell[items_count];
+ };
+
+First, let's describe what a "complex deletion" means. A "complex deletion" is a deletion applied to all the items (or sub-cells) of a complex cell. For instance, for a collection, this corresponds to a full collection deletion. Note that if complex_deletion is absent, individual items (sub-cells) can still be deleted within a complex cell.
+
+The presence or absence of `complex_deletion_time` is determined by the `HAS_COMPLEX_DELETION` flag in row `flags`. Interestingly, this flag is set if any of row complex columns has a complex deletion, so in practice, it will be written for all the complex columns if at least one of them has been entirely deleted in the current row.
+
+Next, the number of items of the current complex cell (aka sub-cells) is stored as a `varint`.
+
+Lastly, we have the complex cell items serialised one by one. They, in fact, represent simple cells that have an additional `path` component that allows to distinguish them.
+
+.. code:: cpp
+
+ struct cell_path {
+ varint length;
+ byte value[length];
+ };
+
+As of today, the only implementation of the `cell_path` is the one for collections so it always has a single value which is:
+
+* an auto-generated `timeuuid` for lists
+* the current map key for maps
+* the actual value for sets (the `complex_cell_item.value` is empty in this case)
+
+Range Tombstone Marker
+----------------------
+
+References:
+
+* `RangeTombstoneMarker.java`_
+
+* `RangeTombstoneBoundMarker.java`_
+
+* `RangeTombstoneBoundaryMarker.java`_
+
+.. _`RangeTombstoneMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneMarker.java
+
+.. _`RangeTombstoneBoundMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneBoundMarker.java
+
+.. _`RangeTombstoneBoundaryMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneBoundaryMarker.java
+
+In SSTables, we have a notion of range tombstones that represent tombstones that cover a slice/range of rows.
+Since 3.0, they are stored as pairs of range tombstone markers indicating its start and its end so that each tombstone corresponds to two ordered `unfiltered` objects or ``range_tombstone_marker`` type. This is done to simplify merging. The ordering of ``unfiltered`` by their clustering prefixes makes sure that a range tombstone start marker precedes any rows covered by the range and a range tombstone end marker goes after them.
+Given that, it becomes clear that as a reader advances through a data file, it has to maintain only up to one range tombstone deletion mark. If the deletion mark is filled, all the rows read are considered deleted until the corresponding end marker is met.
+
+Every range tombstone marker can be either a `range_tombstone_bound_marker`, which represents a single bound of a slice or a `range_tombstone_boundary_marker`, which represents a boundary between two adjacent range tombstones and notifies an "open end, closed start" type of bound. The latter makes for both disk space savings (requires 1 range tombstone marker instead of 2) and simplifies the merging logic of the database storage engine.
+
+.. code:: cpp
+
+ struct range_tombstone_marker {
+ byte flags = IS_MARKER;
+ byte kind_ordinal;
+ be16 bound_values_count;
+ struct clustering_block[] clustering_blocks;
+ varint marker_body_size;
+ varint prev_unfiltered_size;
+ };
+
+
+The first byte represents `flags` which for a range tombstone marker always contain a single ``IS_MARKER`` flag.
+Next byte is a slice bound kind ordinal:
+
+.. code:: cpp
+
+ enum class bound_kind : uint8_t {
+ EXCL_END_BOUND = 0,
+ INCL_START_BOUND = 1,
+ EXCL_END_INCL_START_BOUNDARY = 2,
+ STATIC_CLUSTERING = 3,
+ CLUSTERING = 4,
+ INCL_END_EXCL_START_BOUNDARY = 5,
+ INCL_END_BOUND = 6,
+ EXCL_START_BOUND = 7
+ };
+
+It can be one of {0, 1, 6, 7} for a ``range_tombstone_bound_marker`` and either 2 or 5 for a ``range_tombstone_boundary_marker``.
+Next, the two-byte integer value of the number of non-null columns in the clustering prefix is stored, followed by clustering blocks that are serialised in the exact same way as for rows.
+> For rows, the length of the clustering prefix is not stored as it is always full, meaning that all its clustering columns are non-`null`. For a range tombstone marker, however, the trailing columns can be `null` and so we need to know how many cells are encoded in the clustering blocks.
+
+After that, the size of the marker body is stored as a `varint`, followed by another `varint` that contains the size of the previous unfiltered (row or range tombstone marker).
+
+Next fields depend on whether this range tombstone marker is a bound or a boundary.
+
+.. code:: cpp
+
+ struct range_tombstone_bound_marker
+ : range_tombstone_marker {
+ struct delta_deletion_time deletion_time;
+ };
+
+ struct range_tombstone_boundary_marker
+ : range_tombstone_marker {
+ struct delta_deletion_time end_deletion_time;
+ struct delta_deletion_time start_deletion_time;
+ };
+
+For a bound marker, it stores its delta-encoded deletion time, and for boundary marker, we store two delta-encoded deletion time structures, one for the end bound and another for the start bound within the boundary.
+
+Shadowable Deletion
+-------------------
+
+Initially, an extended `HAS_SHADOWABLE_DELETION` flag has been introduced in 3.0 format to solve a tricky problem described in [CASSANDRA-10261](https://issues.apache.org/jira/browse/CASSANDRA-10261). Later some other problems have been discovered ([CASSANDRA-11500](https://issues.apache.org/jira/browse/CASSANDRA-11500)) which led to a more generic approach that deprecated shadowable tombstones and used expired liveness info instead.
+
+As a result, this flag is not supposed to be written for new SSTables by Cassandra.
+Scylla tracks the presence of this flag and fails to load files that have it set.
+
+
+References
+----------
+
+* `Putting some structure in the storage engine <https://www.datastax.com/2015/12/storage-engine-30>`_ - An overview of the main features of the SSTables 3.0 format including some measurements of disk space savings compared to 2.x.
+
+* `Introduction To The Apache Cassandra 3.x Storage Engine <https://thelastpickle.com/blog/2016/03/04/introductiont-to-the-apache-cassandra-3-storage-engine.html>`_ - A detailed article on SSTables 3.0 data file format with lots of references to the relevant code parts. This article has a few inaccuracies like complex cells format but otherwise is a great read with a lot of useful details.
+
+* `About Deletes and Tombstones in Cassandra <http://thelastpickle.com/blog/2016/07/27/about-deletes-and-tombstones.html>`_ - An article that covers tombstones in SSTables 3.0 in a great detail.
+
+* `Overview of CASSANDRA-8099 changes <https://apache.googlesource.com/cassandra/+show/cassandra-3.0.0-rc2/guide_8099.md>`_ - An engineering description of changes in SSTables data format in Cassandra 3.0. Explains well a variety of higher-level concepts and sheds light on some lower-level implementation details.
+
+* There is hardly any documentation that would be more accurate and up-to-date than the actual `source code <https://github.com/apache/cassandra/tree/cassandra-3.0>`_.
+
+.. include:: /rst_include/apache-copyrights.rst
+
\ No newline at end of file
diff --git a/docs/architecture/sstable/sstable3/sstables-3-index.rst b/docs/architecture/sstable/sstable3/sstables-3-index.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-index.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-index.rst
@@ -0,0 +1,162 @@
+SSTables 3.0 Index File Format
+==============================
+
+.. versionadded:: 3.0
+
+The SSTables index file, together with the :doc:`SSTables summary file </architecture/sstable/sstable3/sstables-3-summary/>` , provides a way to efficiently locate a partition with a specific key or some position within a partition in the :doc:`SSTables data file</architecture/sstable/sstable3/sstables-3-data-file-format/>`.
+
+Broadly, the index file lists the keys in the data file in order, giving for each key its position in the data file. The summary file, which is held in memory, contains samples of these keys, pointing to their position in the index file. So to efficiently search for a specific key, we use the summary to find a (relatively short) range of positions in the index file which may hold this key, then read this range from the index file and look for the specific key. The details on how to further pinpoint specific columns inside very long partitions are explained below.
+
+The Index File Layout
+.....................
+
+Building Blocks
+---------------
+
+The :ref:`building blocks <sstables-3-building-blocks>` of the new index format are same as those of the new data format.
+This includes ``varints``, ``optional`` values and delta encoding.
+
+Description
+-----------
+
+The index file format changes in v3.0 from the :doc:`old format </architecture/sstable/sstable2/sstable-format>` are moderate compared to how significantly has changed the data file layout. Still, there are some new fields and entities that are worth a detailed look. Such fields are the ``offsets`` array added to ``index_entry`` and ``end_open_marker`` structure added to ``promoted_index_block``.
+
+The index file is a long sequence of entries:
+
+.. code:: cpp
+
+ struct index_file {
+ struct index_entry entries[];
+ };
+
+ struct index_entry {
+ be16 key_length;
+ char key[key_length];
+ varint position; // decoded into a 64-bit integer
+ varint promoted_index_length; // decoded into a 32-bit integer
+ byte promoted_index[promoted_index_length];
+ };
+
+Here, key is the SSTable partition key, and position is the position of that partition in the data file.
+
+For large partitions, finding a specific range of columns requires more than just starting position to be efficient. For those, the so-called promoted index is stored along. It samples partition at roughly ``column_index_size_in_kb`` (by default, 64 KB) blocks and gives the clustering prefixes range for each block.
+
+The reason for the strange name ``promoted index`` is that it originally started as a separately stored column index, until in `Cassandra 1.2`_, when it was "promoted" to live inside the SSTables index file, reducing the number of seeks required to find a given column from 3 to 2.
+
+.. _`Cassandra 1.2`: https://issues.apache.org/jira/browse/CASSANDRA-2319
+
+The ``promoted_index_length`` stores the number of bytes right after this field and up to the end of the current ``index_entry``. If ``promoted_index_length`` is 0, there is no promoted index for this entry and nothing follows it.
+
+The structure of promoted index (when ``promoted_index_length != 0``) is as follows:
+
+.. code:: cpp
+
+ struct promoted_index {
+ varint partition_header_length; //decoded into a 64-bit integer
+ struct deletion_time deletion_time;
+ varint promoted_index_blocks_count; // decoded into a 32-bit integer
+ struct promoted_index_block blocks[promoted_index_blocks_count];
+ be32 offsets[promoted_index_blocks_count];
+ }
+
+The first field, ``partition_header_length``, stores the length of serialized partition key, partition tombstone and static row, if present, in the data file. This allows to skip over the partition prefix straight to the first clustered row.
+
+
+
+The `deletion time` structure is described in :doc:`SSTables 3.0 data file format</architecture/sstable/sstable3/sstables-3-data-file-format/>` article. It is simply a copy of the partition ``deletion_time``, either live or a partition tombstone. We need this copy inside the index, because normally the deletion_time of a partition appears in its very beginning in the data file, but with the promoted index we intend to skip directly to the middle of a very large partition, so we don't want to also read the beginning of the partition just to read its partition tombstone.
+
+After deletion time mark, the number of promoted index blocks is stored as a `varint`. It can be zero for small partitions or >= 2 (apparently, it makes no sense to store a single promoted index block).
+
+Promoted Index Blocks
+---------------------
+
+The promoted index block looks like:
+
+.. code:: cpp
+
+ struct promoted_index_block {
+ struct clustering_prefix first_name;
+ struct clustering_prefix last_name;
+ varint offset;
+ varint delta_width;
+ byte end_open_marker_present;
+ optional<struct deletion_time> end_open_marker;
+ };
+
+Clustering Prefixes
+-------------------
+
+Here, ``first_name`` and ``last_name`` are the serialised prefixes of clustering columns marking the boundaries of the block. They are stored as follows:
+
+.. code:: cpp
+
+ struct clustering_prefix {
+ byte kind;
+ optional<be16> size;
+ struct clustering_block clustering_blocks[];
+ };
+
+The first byte, `kind`, stores the serialised ordinal of the value from the ``bound_kind`` enum (see :doc:`SSTables 3.0 data file format</architecture/sstable/sstable3/sstables-3-data-file-format/>`) for the enum definition).
+It can be either 4 (for `CLUSTERING`) when corresponds to a row or one of 0, 1 and 2 (for ``EXCL_END_BOUND``, ``INCL_START_BOUND`` or ``EXCL_END_INCL_START_BOUNDARY`` accordingly) for a range tombstone marker.
+
+The next field, ``size``, is only present for range tombstone markers, i.e., when ``kind != 4``. It contains the actual number of values in the clustering prefix (the prefix length). For rows, it is not needed as rows have all the clustering columns values (full clustering prefix) so the count is taken from the table schema definition.
+
+The sequence of clustering blocks is serialised in exactly the same way as clustering blocks in rows or range tombstone markers in data files. You can refer to the detailed description :ref:`here <sstables-3-building-blocks>`
+
+
+Other Promoted Index Blocks Fields
+----------------------------------
+
+The ``offset`` field stores the start of the block relative to the beginning of the current partition in the data file.
+
+The `width` field is a delta-encoded value representing the length of the current promoted index block in the index file. The size of promoted index blocks is a configurable value set through the ``column_index_size_in_kb`` option in the config file. It defaults to 64KB and this is the base value that `width` delta is taken from.
+
+As of today, the base value is not stored along in the index file and always equals 64KB == 65536.
+
+Note that since the actual promoted index block size can be configured to be less than 64K, it can so happen that delta-encoding width would result in a negative value. Because of that, the stored value should be treated as **signed**.
+
+The next byte after `width` called ``end_open_marker_present`` is effectively a `boolean` which tells us whether the following ``end_open_marker`` structure is serialised or not. If ``end_open_marker_present`` is 1, ``end_open_marker`` should be read.
+
+The ``end_open_marker`` structure is present in case if the end bound of the current promoted index block falls in between two range tombstone markers denoting a range.
+In other words, that means that the block of ``unfiltereds`` in the data file that corresponds to this promoted index block contains a range tombstone start marker but its counterpart (range tombstone end marker) lies somewhere past that block.
+It is set for a range tombstone marker of either the ``INCL_START_BOUND`` or the ``EXCL_END_INCL_START_BOUNDARY`` kind and contains the open bound deletion time.
+
+The ``end_open_marker`` has to do with how range tombstones are organised in SSTables 3.0. and is closely connected with the merging logic of storage engine code. That code expects all the data it reads from SSTables to come strictly ordered and it expects range tombstone markers to always come in pairs (the combined "boundary" type marker is just treated as two markers - an end marker for the previous RT followed immediately by a start marker for a new RT.
+So when a slice of data is being read, it may contain an end RT marker without the corresponding start RT marker. In order to properly handle this, reader code returns a start RT marker corresponding to the slice start bound with the deletion time taken from the ``end_open_marker`` structure see: SSTableIterator.java.handlePreSliceData_
+
+.. _SSTableIterator.java.handlePreSliceData: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/columniterator/SSTableIterator.java#L125
+
+The higher-level reason for this design is that C* 3.0 storage design aims to be as iterator-based as possible and as such doesn't re-arrange the data it reads (and without start RT marker, such re-arrangement would be due).
+
+Lastly, there is an `offsets` array which stores the offsets for all the promoted index blocks.
+Its size is the same as the value stored in ``promoted_index_blocks_count``. The first offset is always 0, and others are the offsets of corresponding promoted index blocks from the beginning of ``promoted_index.blocks``.
+
+It is possible to read those offsets (commonly referred to as "offsets map") directly without reading the entire promoted index. This, in turn, allows searching through the promoted index using binary search which results in O(log N) reads instead of O (N).
+
+References
+..........
+
+The following code parts in Cassandra deal with index serialisation/de-serialisation:
+
+* `ColumnIndex.java, buildRowIndex`_
+
+* `RowIndexEntry.java`_
+
+* `IndexInfo.java`_
+
+.. _`ColumnIndex.java, buildRowIndex`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/ColumnIndex.java
+
+.. _`IndexInfo.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/IndexInfo.java
+
+.. _`RowIndexEntry.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/RowIndexEntry.java
+
+
+Additional Information
+----------------------
+
+The offset map reduces the complexity of search in the promoted index from O(N) to O(log N) using the offsets map.
+There are some better alternatives that should further improve the performance of index-related operations using BTree-like structures. They are not released yet but planned for Cassandra 4. See `CASSANDRA-9754`_.
+
+.. _`CASSANDRA-9754`: https://issues.apache.org/jira/browse/CASSANDRA-9754
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-statistics.rst b/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
@@ -0,0 +1,294 @@
+SSTables 3.0 Statistics File Format
+===================================
+
+.. versionadded:: 3.0
+
+This file stores metadata for SSTable. There are 4 types of metadata:
+
+1. **Validation metadata** - used to validate SSTable correctness.
+2. **Compaction metadata** - used for compaction.
+3. **Statistics** - some information about SSTable which is loaded into memory and used for faster reads/compactions.
+4. **Serialization header** - keeps information about SSTable schema.
+
+General structure
+.................
+
+The file is composed of two parts. First part is a table of content which allows quick access to a selected metadata. Second part is a sequence of metadata stored one after the other.
+Let's define array template that will be used in this document.
+
+.. code:: cpp
+
+ struct array<LengthType, ElementType> {
+ LengthType number_of_elements;
+ ElementType elements[number_of_elements];
+ }
+
+
+Table of content
+
+.. code:: cpp
+
+ using toc = array<be32<int32_t>, toc_entry>;
+
+ struct toc_entry {
+ // Type of metadata
+ // | Type | Integer representation |
+ // |----------------------|------------------------|
+ // | Validation metadata | 0 |
+ // | Compaction metadata | 1 |
+ // | Statistics | 2 |
+ // | Serialization header | 3 |
+ be32<int32_t> type;
+ // Offset, in the file, at which this metadata entry starts
+ be32<int32_t> offset;
+ }
+
+The toc array is sorted by the type field of its members.
+
+Validation metadata entry
+.........................
+
+.. code:: cpp
+
+ struct validation_metadata {
+ // Name of partitioner used to create this SSTable.
+ // Represented by UTF8 string encoded using modified UTF-8 encoding.
+ // You can read more about this encoding in:
+ // https://docs.oracle.com/javase/7/docs/api/java/io/DataInput.html#modified-utf-8
+ // https://docs.oracle.com/javase/7/docs/api/java/io/DataInput.html#readUTF()
+ Modified_UTF-8_String partitioner_name;
+ // The probability of false positive matches in the bloom filter for this SSTable
+ be64<double> bloom_filter_fp_chance;
+ }
+
+Compaction metadata entry
+.........................
+
+.. code:: cpp
+
+ // Serialized HyperLogLogPlus which can be used to estimate the number of partition keys in the SSTable.
+ // If this is not present then the same estimation can be computed using Summary file.
+ // Encoding is described in:
+ // https://github.com/addthis/stream-lib/blob/master/src/main/java/com/clearspring/analytics/stream/cardinality/HyperLogLogPlus.java
+ using compaction_metadata = array<be32<int32_t>, be8>;
+
+Statistics entry
+................
+
+This entry contains some parts of ``EstimatedHistogram``, ``StreamingHistogram`` and ``CommitLogPosition`` types. Let's have a look at them first.
+
+EstimatedHistogram
+------------------
+
+.. code:: cpp
+
+ // Each bucket represents values from (previous bucket offset, current offset].
+ // Offset for last bucket is +inf.
+ using estimated_histogram = array<be32<int32_t>, bucket>;
+
+ struct bucket {
+ // Offset of the previous bucket
+ // In the first bucket this is offset of the first bucket itself because there's no previous bucket.
+ // The offset of the first bucket is repeated in second bucket as well.
+ be64<int64_t> prev_bucket_offset;
+ // This bucket value
+ be64<int64_t> value;
+ }
+
+StreamingHistogram
+------------------
+
+.. code:: cpp
+
+ struct streaming_histogram {
+ // Maximum number of buckets this historgam can have
+ be32<int32_t> bucket_number_limit;
+ array<be32<int32_t>, bucket> buckets;
+ }
+
+ struct bucket {
+ // Offset of this bucket
+ be64<double> offset;
+ // Bucket value
+ be64<int64_t> value;
+ }
+
+CommitLogPosition
+-----------------
+
+.. code:: cpp
+
+ struct commit_log_position {
+ be64<int64_t> segment_id;
+ be32<int32_t> position_in_segment;
+ }
+
+
+Whole entry
+-----------
+
+.. code:: cpp
+
+ struct statistics {
+ // In bytes, uncompressed sizes of partitions
+ estimated_histogram partition_sizes;
+ // Number of cells per partition
+ estimated_histogram column_counts;
+ commit_log_position commit_log_upper_bound;
+ // Typically in microseconds since the unix epoch, although this is not enforced
+ be64<int64_t> min_timestamp;
+ // Typically in microseconds since the unix epoch, although this is not enforced
+ be64<int64_t> max_timestamp;
+ // In seconds since the unix epoch
+ be32<int32_t> min_local_deletion_time;
+ // In seconds since the unix epoch
+ be32<int32_t> max_local_deletion_time;
+ be32<int32_t> min_ttl;
+ be32<int32_t> max_ttl;
+ // compressed_size / uncompressed_size
+ be64<double> compression_rate;
+ // Histogram of cell tombstones.
+ // Keys are local deletion times of tombstones
+ streaming_histogram tombstones;
+ be32<int32_t> level;
+ // The difference, measured in milliseconds, between repair time and midnight, January 1, 1970 UTC
+ be64<int64_t> repaired_at;
+ // Minimum and Maximum clustering key prefixes present in the SSTable (valid since the "md" SSTable format).
+ // Note that:
+ // - Clustering rows always have the full clustering key.
+ // - Range tombstones may have a partial clustering key prefix.
+ // - Partition tombstones implicitly apply to the full, unbound clustering range.
+ // Therefore, an empty (min|max)_clustering_key denotes a respective unbound range,
+ // derived either from an open-ended range tombstone, or from a partition tombstone.
+ clustering_bound min_clustering_key;
+ clustering_bound max_clustering_key;
+ be8<bool> has_legacy_counters;
+ be64<int64_t> number_of_columns;
+ be64<int64_t> number_of_rows;
+
+ // Version MA of SSTable 3.x format ends here.
+ // It contains only one commit log position interval - [NONE = new CommitLogPosition(-1, 0), upper bound of commit log]
+
+ commit_log_position commit_log_lower_bound;
+
+ // Version MB of SSTable 3.x format ends here.
+ // It contains only one commit log position interval - [lower bound of commit log, upper bound of commit log].
+
+ array<be32<int32_t>, commit_log_interval> commit_log_intervals;
+ }
+
+ using clustering_bound = array<be32<int32_t>, clustering_column>;
+ using clustering_column = array<be16<uint16_t>, be8>;
+
+ struct commit_log_interval {
+ commit_log_position start;
+ commit_log_position end;
+ }
+
+
+Serialization header
+....................
+
+.. code:: cpp
+
+ struct serialization_header {
+ vint<uint64_t> min_timestamp;
+ vint<uint32_t> min_local_deletion_time;
+ vint<uint32_t> min_ttl;
+ // If partition key has one column then this is the type of this column.
+ // Otherwise, this is a CompositeType that contains types of all partition key columns.
+ type partition_key_type;
+ array<vint<uint32_t>, type> clustering_key_types;
+ columns static_columns;
+ columns regular_columns;
+ }
+
+ using columns = array<vint<uint32_t>, column>;
+
+ struct column {
+ array<vint<uint32_t>, be8> name;
+ type column_type;
+ }
+
+ // UTF-8 string
+ using type = array<vint<uint_32_t>, be8>;
+
+Type encoding
+-------------
+
+Type is just a byte buffer with an unsigned variant integer (32-bit) length. It is a UTF-8 string. All leading spaces, tabs and newlines are skipped. Null or empty string is a bytes type. First segment of non-blank characters should contain only alphanumerical characters and special chars like ``'-'``, ``'+'``, ``'.'``, ``'_'``, ``'&'``. This is the name of the type. If type name does not contain any '.' then it gets "org.apache.cassandra.db.marshal." prepended to itself. Then an "instance" static field is taken from this class. If the first non-blank character that follows type name is '(' then "getInstance" static method is invoked instead. Remaining string is passed to this method as a parameter. There are following types:
+
+======================= ============
+Type Parametrized
+======================= ============
+Ascii Type No
+----------------------- ------------
+Boolean Type No
+----------------------- ------------
+Bytes Type No
+----------------------- ------------
+Byte Type No
+----------------------- ------------
+ColumnToCollection Type Yes
+----------------------- ------------
+Composite Type Yes
+----------------------- ------------
+CounterColumn Type No
+----------------------- ------------
+Date Type No
+----------------------- ------------
+Decimal Type No
+----------------------- ------------
+Double Type No
+----------------------- ------------
+Duration Type No
+----------------------- ------------
+DynamicComposite Type Yes
+----------------------- ------------
+Empty Type No
+----------------------- ------------
+Float Type No
+----------------------- ------------
+Frozen Type Yes
+----------------------- ------------
+InetAddress Type No
+----------------------- ------------
+Int32 Type No
+----------------------- ------------
+Integer Type No
+----------------------- ------------
+LexicalUUID Type No
+----------------------- ------------
+List Type Yes
+----------------------- ------------
+Long Type No
+----------------------- ------------
+Map Type Yes
+----------------------- ------------
+PartitionerDefinedOrder Yes
+----------------------- ------------
+Reversed Type Yes
+----------------------- ------------
+Set Type Yes
+----------------------- ------------
+Short Type No
+----------------------- ------------
+SimpleDate Type No
+----------------------- ------------
+Timestamp Type No
+----------------------- ------------
+Time Type No
+----------------------- ------------
+TimeUUID Type No
+----------------------- ------------
+Tuple Type Yes
+----------------------- ------------
+User Type Yes
+----------------------- ------------
+UTF8 Type No
+----------------------- ------------
+UUID Type No
+======================= ============
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-summary.rst b/docs/architecture/sstable/sstable3/sstables-3-summary.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-summary.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-summary.rst
@@ -0,0 +1,110 @@
+SSTables 3.0 Summary File Format
+================================
+
+.. versionadded:: 3.0
+
+SSTables summary file contains samples of keys that are used for the first, coarse-grained, stage of search through the index. Every summary entry points to a sequence of index entries commonly referred to as an index page where the key looked for is located. So with the summary, it is possible to only read and search through a small part of the index.
+
+The summary file is meant to be read and stored entirely in memory, therefore it is aimed to be reasonably small. This incurs some trade-off between the size of the summary and the cardinality of an index page (number of index entries covered by it). The less the cardinality is, the better precision the initial lookup through summary gives, but this also tends to increase the size of the summary. The balance between the two is regulated by the sampling level which rules how many index entries should one summary entry cover.
+
+SSTables Summary File Layout
+............................
+
+The summary file format in SSTables 3.0 has minimal changes compared to the previous version of the format described here: :doc:`SSTable 2.0 format </architecture/sstable/sstable2/sstable-format/>`
+The only noticeable change is that in 3.0 the summary file does not store information about segment boundaries. See `CASSANDRA-8630`_ for more details about this change.
+
+.. _`CASSANDRA-8630`: https://issues.apache.org/jira/browse/CASSANDRA-8630
+
+Other than that, the data format remains the same. Note that, unlike data and index files, the summary file does not make use of variable-length integers:
+
+.. code:: cpp
+
+ struct summary {
+ struct summary_header header;
+ struct summary_entries_block summary_entries;
+ struct serialized_key first;
+ struct serialized_key last;
+ };
+
+
+Summary Header
+--------------
+
+First goes the summary `header` which is laid out as follows:
+
+.. code:: cpp
+
+ struct summary_header {
+ be32 min_index_interval;
+ be32 entries_count;
+ be64 summary_entries_size;
+ be32 sampling_level;
+ be32 size_at_full_sampling;
+ };
+
+
+The ``min_index_interval`` is a lower bound for the average number of partitions in between each index summary entry. A lower value means that more partitions will have an entry in the index summary when at the full sampling level.
+
+The ``entries_count`` is the number of `offsets` and ``entries`` in the ``summary_entries`` structure (see below).
+
+The ``summary_entries_size`` is the full size of the ``summary_entries`` structure (see below).
+
+The ``sampling_level`` is a value between 1 and ``BASE_SAMPLING_LEVEL`` (which equals to 128) that represents how many of the original index summary entries ``((1 / indexInterval) * numKeys)`` have been retained. Thus, this summary contains ``(samplingLevel / BASE_SAMPLING_LEVEL) * ((1 / indexInterval) * numKeys))`` entries.
+
+The ``size_at_full_sampling`` is the number of entries the Summary **would** have if the sampling level would be equal to ``min_index_interval``.
+
+Summary Entries
+---------------
+
+.. code:: cpp
+
+ struct summary_entries_block {
+ uint32 offsets[header.entries_count];
+ struct summary_entry entries[header.entries_count];
+ };
+
+
+The ``offsets`` array contains offsets of corresponding entries in the ``entries`` array below. The offsets are taken from the beginning of the ``summary_entries_block`` so ``offsets[0] == sizeof(uint32) * header.entries_count`` as the first entry begins right after the array of offsets.
+
+Note that ``offsets`` are written in the native order format although typically all the integers in SSTables files are written in big-endian. In Scylla, they are always written in little-endian order to allow interoperability with 1. Summary files written by Cassandra on the more common little-endian machines, and 2. Summary files written by Scylla on the rarer big-endian machines.
+
+Here is how a summary entry looks:
+
+.. code:: cpp
+
+ struct summary_entry {
+ byte key[]; // variable-length.
+ be64 position;
+ };
+
+
+Every ``summary_entry`` holds a `key` and a ``position`` of the index entry with that key in the index file.
+Note that ``summary_entry`` does not store key length but it can be deduced from the offsets. The length of the last ``summary_entry`` in the `entries` array can be calculated using its offset and ``header.summary_entries_size``.
+
+Keys
+----
+
+The last two entries in the ``summary`` structure are ``serialized_keys`` that look like:
+
+.. code:: cpp
+
+ struct serialized_key {
+ be32 size;
+ byte key[size];
+ };
+
+
+They store the first and the last keys in the index/data file.
+
+References
+
+* `IndexSummary.java`_
+
+* `SSTableReader.java, saveSummary`_
+
+.. _`IndexSummary.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/IndexSummary.java
+
+.. _`SSTableReader.java, saveSummary`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/format/SSTableReader.java
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/contribute.rst b/docs/contribute.rst
--- a/docs/contribute.rst
+++ b/docs/contribute.rst
@@ -0,0 +1,31 @@
+Contribute to Scylla
+====================
+
+Thank you for your interest in making Scylla better!
+We appreciate your help and look forward to welcoming you to the Scylla Community.
+There are two ways you can contribute:
+
+* Send a patch to the Scylla source code
+* Write documentation for Scylla Docs
+
+
+Contribute to Scylla's Source Code
+----------------------------------
+Scylla developers use patches and email to share and discuss changes.
+Setting up can take a little time, but once you have done it the first time, it’s easy.
+
+The basic steps are:
+
+* Join the Scylla community
+* Create a Git branch to work on
+* Commit your work with clear commit messages and sign-offs.
+* Send a PR or use ``git format-patch`` and ``git send-email`` to send to the list
+
+
+The entire process is `documented here <https://scylla.docs.scylladb.com/master/contribute/index>`_.
+
+Contribute to Scylla Docs
+-------------------------
+
+Each Scylla project has accompanying documentation. For information about contributing documentation to a specific Scylla project, refer to the README file for the individual project.
+For general information or to contribute to the Scylla Sphinx theme, read the `Contributor's Guide <https://sphinx-theme.scylladb.com/stable/contribute/>`_.
\ No newline at end of file
diff --git a/docs/faq.rst b/docs/faq.rst
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -0,0 +1,498 @@
+===========
+Scylla FAQ
+===========
+
+.. meta::
+ :title:
+ :description: Frequently Asked Questions about ScyllaDB
+ :keywords: questions, Scylla, ScyllaDB, DBaaS, FAQ, error, problem
+
+Performance
+-----------
+
+I’m not getting the level of performance I expected. What’s wrong?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Lower than expected performance can be a result of many factors, from HW (storage, CPU, network) to data modeling to the application layer.
+As a first step, make sure to have |mon_root| in place. Looking at the Scylla dashboard is the best way to look for bottlenecks.
+If you need our help, please follow :doc:`How to Report a Performance Problem </troubleshooting/report-scylla-problem/>` to share data securely.
+
+Scylla is using all of my memory! Why is that? What if the server runs out of memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla uses available memory to cache your data. Scylla knows how to dynamically manage memory for optimal performance; for example, if many clients connect to Scylla, it will evict some data from the cache to make room for these connections; when the connection count drops again, this memory is returned to the cache.
+
+Can I limit Scylla to use less CPU and memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The :code:`--smp` option (for instance, :code:`--smp 2`) will restrict Scylla to a smaller number of CPUs. It will still use 100 % of those CPUs, but at least won’t take your system out completely. An analogous option exists for memory: :code:`-m`.
+
+Do I ever need to disable the Scylla cache to use less memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+It is not possible to turn off the Scylla cache. But cache problems do not arise in normal operation. Scylla can use up to 50% of memory for cache, and will dynamically evict rows from the cache if they are too large. So the only possibility of getting an out of memory error is if a single row is bigger than 50% of the memory for a shard. This is (total_machine_memory / (number_of_lcores * 2)).
+
+For a 64GB machine with 16 cores and hyperthreading enabled, you have 2GB per shard, of which the cache can use 1GB per shard. With such large rows, you will have other problems. We recommend staying with rows that are less than a few megabytes maximum size.
+
+What are some of the techniques Scylla uses to achieve its performance?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla tries to utilize all available resources (processor cores, memory, storage, and networking) by always operating in parallel and never blocking. If Scylla needs to read a disk block, it initiates the read and immediately moves on to another task. Later, when the read completes Scylla resumes the original task from where it left off. By never blocking, a high degree of concurrency is achieved, allowing all resources to be utilized to their limit.
+Read more on Scylla Architecture:
+
+* `Scylla Technology <http://www.scylladb.com/product/technology/>`_
+* `Scylla Memory Management <http://www.scylladb.com/product/technology/memory-management/>`_
+
+I thought that Scylla's underlying `Seastar framework <https://github.com/scylladb/seastar>`_ uses one thread per core, but I see more than two threads per core. Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Seastar creates an extra thread per core for blocking syscalls (like :code:`open()`/ :code:`fsync()` / :code:`close()` ); this allows the Seastar reactor to continue executing while a blocking operation takes place. Those threads are usually idle, so they don’t contribute to significant context switching activity.
+
+I’m seeing X compaction running in parallel on a single Scylla node. Is it normal?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Yes, for more than one reason:
+
+* each shard (core) will run its compactions independently, often at the same time,
+* each table will run its compactions independently, often at the same time
+* depending on the compaction strategy, more than one compaction can run in parallel. For example in Sized Tier Compaction Strategy (STCS), large sstable compaction can take time, allowing smaller sstable to be compacted at the same time
+
+.. _faq-io:
+
+Setting io.conf configuration for HDD storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As part of the Scylla setup process, **iotune** runs a short benchmark of your storage. When completed, it generates the `/etc/scylla.d/io.conf` configuration file. Note that iotune has known issues benchmarking HDD storage.
+
+.. note:: This section is not relevant in 2.3
+
+Therefore, when using Scylla with HDD storage, it is recommended to use RAID0 on all of your available disks, and manually update the `io.conf` configuration file `max-io-request` parameter. This parameter sets the number of concurrent requests sent to the storage. The value for this parameter should be 3X (3 times) the number of your disks. For example, if you have 3 disks, you would set `max-io-request=9`.
+
+How many connections is it recommended to open from each Scylla client application?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As a rule of thumb, for Scylla's best performance, each client needs at least 1-3 connection per Scylla core.
+For example, a cluster with three nodes, each node with 16 cores, each client application should open 32 (2x16) connections to each Scylla node.
+
+Do I need to configure ``swap`` on a Scylla node?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, configuring ``swap`` on a Scylla node is recommended.
+``swap`` size should be set to either ``total_mem``/3 or 16GB - lower of the two.
+
+``total_mem`` is the total size of the nodes memory.
+
+For example:
+
+* If the node ``total_mem`` is 18GB ``swap`` size should be set to 6GB.
+
+* If the node ``total_mem`` is 240GB ``swap`` size should be set to 16GB.
+
+Swap can be set up in several ways. One way to set up swap is detailed in the KB Article :doc:`How to Set up a Swap Space </kb/set-up-swap>`.
+
+After upgrade from Scylla 2.1 and older, scylla_reactor_utilization metrics is at high percentage (high CPU utilization is observed). Why does this happen?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla 2.2 enables the compaction automatic controller which was not present prior to version 2.2. What this means is that in Scylla 2.1 (and earlier) the system waits for 4 SSTables to be present in the same tier before starting a compaction. In Scylla 2.2 (and later), compactions can be controlled to not impact the workload. This means that workloads which have been considered as backlog in Scylla 2.1 and earlier, in Scylla 2.2 and later are not.
+
+My query does not return any or some of the data? What happened?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you are using a time range in the query, refer to the solution in the troubleshooting document, :doc:`Time Range Queries Do Not Return Some or All of the Data </troubleshooting/time-zone>`.
+
+
+DESC SCHEMA shows that I am using many materialized views (MVs) when I know I only added Secondary Indexes (SI). Why are there MVs in my schema?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As SI is built ontop of MV, you can expect to see MV in your schema. There is nothing wrong with your system. More information on :doc:`Global Secondary Indexes </using-scylla/secondary-indexes>`.
+
+
+Using the Java driver SimpleStatements are slow. Why does this happen?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Java driver's `SimpleStatement <https://java-driver.docs.scylladb.com/stable/manual/statements/simple/>`_ is token unaware by default. This means that requests sent out will reach the Controller node before it is known which shard it's supposed to access. We suggest using `PreparedStatements <https://java-driver.docs.scylladb.com/stable/manual/statements/prepared/>`_ instead.
+
+Disk Space
+-----------
+
+.. _reclaim-space:
+
+Dropping a table does not reduce storage used by Scylla, how can I clean the disk from dropped tables?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+scylla.yaml includes an ``auto_snapshot`` parameter; when true (it is by default), Scylla creates a snapshot for a table just before dropping it, as a safety measure.
+You can find the snapshot in the ``snapshots`` directory, under the table SSTable. For example, for dropped table ``users`` in keyspace ``mykeyspace``:
+
+:code:`/var/lib/scylla/data/mykeyspace/users-bdba4e60f6d511e7a2ab000000000000/snapshots/1515678531438-users`
+
+
+As the snapshot take the same space as the dropped table, disk usage will remain the same.
+You can clean snapshots by using :doc:`nodetool clearsnapshot </operating-scylla/nodetool-commands/clearsnapshot>`. Read more on :doc:`snapshot and clearsnapshot </operating-scylla/procedures/backup-restore/delete-snapshot/>`
+
+Features
+--------
+Will Scylla have a certain feature in an upcoming release?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Roadmap <http://www.scylladb.com/technology/status/>`_ page for features scheduled for our GA release.
+
+I want to try out new features. How do I enable experimental mode?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You need to add the line :code:`experimental: true` to your :code:`scylla.yaml` file.
+
+1. Launch the file in a text editor: :code:`$ vi /etc/scylla/scylla.yaml`. (Alternately, on docker, it's :code:`$ docker exec -it your_node vi /etc/scylla/scylla.yaml`);
+2. Add the line :code:`experimental: true`;
+3. Save the file and exit.
+4. Stop and restart the node.
+
+ On RedHat Enterprise Linux, CentOS or Ubuntu:
+
+ :code:`$ sudo systemctl restart scylla-server`
+
+ On Docker:
+
+ :code:`$ docker stop <your_node> && docker start <your_node>`
+
+ Alternately, starting from Scylla 2.0, you can start Scylla for Docker with the :code:`experimental` flag as follows:
+
+ :code:`$ docker run --name <your_node> -d scylladb/scylla --experimental 1`
+
+You should now be able to use the experimental features available in your version of Scylla.
+
+How do I check the current version of Scylla that I am running?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* On a regular system or VM (running Ubuntu, CentOS, or RedHat Enterprise): :code:`$ scylla --version`
+
+Check the :doc:`Operating System Support Guide </getting-started/os-support>` for a list of supported operating systems and versions.
+
+* On a docker node: :code:`$ docker exec -it Node_Z scylla --version`
+
+
+Is Scylla Apache Cassandra compatible? Is API / interface X compatible?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Cassandra Compatibility <http://www.scylladb.com/technology/status/#cassandra-compatibility>`_ section for compatibility matrix.
+
+Which version(s) of Apache Cassandra is Scylla compatible with? Will Scylla be compatible with future Cassandra versions?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Cassandra Compatibility <http://www.scylladb.com/technology/status/#cassandra-compatibility>`_ section for current and future Apache Cassandra release compatibility.
+
+
+I am upgrading my nodes to a version that uses a newer SSTable format, when will the nodes start using the new SSTable format?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :doc:`new "mc" SSTable format</architecture/sstable/sstable3/index>` is supported in Scylla 3.0 and later.
+Scylla only starts using the newer format when every node in the cluster is capable to generate it.
+Therefore, only when all nodes in the cluster are upgraded the new format is used.
+
+
+What if I get an error when trying to use cqlsh DESCRIBE commands?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Apache Cassandra 4.0 includes breaking changes in the DESCRIBE command by moving its implementation from the client (cqlsh)
+to the server. As a result, using DESCRIBE in cqlsh from Cassandra 4.0 package with Scylla will result in an error. As a remedy,
+you can do one of the following:
+
+* Use Scylla cqlsh:
+
+ * On Linux, you can install the ``scylla-tools`` package from the official ScyllaDB repository on GitHub.
+ The package contains cqlsh and other Apache Cassandra compatible tools for Scylla.
+ * On Linux, Windows, or Mac, you can run a Scylla container.
+* Downgrade your cqlsh to a version based on Cassandra 3.x, which supports DESCRIBE commands.
+
+.. note::
+ The Scylla roadmap includes moving DESCRIBE to server side, similarly to Cassandra 4.0. See https://github.com/scylladb/scylla/issues/9571 for information about progress.
+
+Ubuntu
+------
+
+.. _faq-check-update-kernel:
+
+Check and update Ubuntu 14.04 kernel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Running Scylla on Ubuntu 14.04 requires kernel 3.15 or later
+
+* To check your kernel version: :code:`$ uname -a`
+* If your kernel is older than 3.15 then:
+
+ * Check for available kernels: :code:`$ sudo apt-cache search linux-image`
+ * Install: :code:`$ sudo apt-get install linux-image-your_version_choice`, for example *linux-image-3.16.0*
+ * restart: :code:`$ sudo reboot now`
+
+Docker
+-------
+
+What if I get an error when connecting an application to a ScyllaDB cluster in Docker?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Connectivity problems may occur if you are trying to connect to the ScyllaDB nodes with their Docker internal IP addresses.
+
+If you need to reach your nodes from outside the internal Docker network, you must expose the appropriate ports to the Docker host.
+See `Error connecting Java Spring application to ScyllaDB Cluster in Docker <https://stackoverflow.com/questions/72165195/error-connecting-java-spring-application-to-scylladb-cluster-in-docker>`_ for more information and an example.
+
+
+Installation
+------------
+Can I install Scylla on an Apache Cassandra server?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla comes with its own version of the Apache Cassandra client tools, in the package :code:`scylla-tools`. Trying to install it on a server with Cassandra already installed may result in something like:
+
+.. code-block:: console
+
+ Unpacking scylla-tools (1.0.1-20160411.b9fe89b-ubuntu1) ...
+ dpkg: error processing archive /var/cache/apt/archives/scylla-tools_1.0.1-20160411.b9fe89b-ubuntu1_all.deb (--unpack):
+ trying to overwrite '/usr/bin/nodetool', which is also in package cassandra 2.1.4
+
+We recommend uninstalling Apache Cassandra before installing :code:`scylla-tools`.
+
+.. _faq-snitch-strategy:
+
+Which snitch or replication strategy should I use?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you are creating a production cluster or if your cluster is going to have more than one data center you need to use a **DC-aware** snitch, e.g. :code:`GossipingPropertyFileSnitch` or :code:`Ec2MultiRegionSnitch`. You will also need to use a **DC-aware** replication strategy, e.g. :code:`NetworkTopologyStrategy`.
+
+However, if you are going to create your first cluster or want to try something simple, if your cluster is going to have a single data center then you may use a :code:`SimpleSnitch` and then use a :code:`SimpleStrategy` for your keyspaces.
+
+Our general recommendation is to always use a :code:`NetworkTopologyStrategy` and use :code:`Ec2XXX` snitches on AWS based clusters and :code:`GossipingPropertyFileSnitch` in all other cases.
+
+A description of all snitch options we support may be found here: `Snitches <https://github.com/scylladb/scylla/wiki/Snitches>`_.
+
+Note: trying to mix a :code:`SimpleSnitch` with a :code:`DC-aware strategy` or a :code:`DC-aware snitch` with a :code:`SimpleStrategy` may cause your cluster not to work as intended therefore we **strongly discourage** these types of configurations in general.
+
+Not using a proper snitch-strategy combination may cause different types of errors.
+
+For instance:
+
+.. code-block:: console
+
+ Unavailable: code=1000 [Unavailable exception] message="Cannot achieve consistency level for cl LOCAL_ONE. Requires 1, alive 0" info={'required_replicas': 1, 'alive_replicas': 0, 'consistency': 'LOCAL_ONE'}
+
+If you see this error you should always check that you are not using a :code:`SimpleSnitch` in your cluster configuration in conjunction with some :code:`DC-aware replication strategy` for a keyspace of a table you are failing to query.
+
+When working with ``GossipingPropertyFileSnitch`` or ``Ec2MultiRegionSnitch`` you should edit the ``cassandra-rackdc.properties``
+
+For node using ``GossipingPropertyFileSnitch``, the file should look like the following:
+
+.. code-block:: cql
+
+ dc=asia_datacenter
+ rack=rack1
+ prefer_local= true
+
+When the node is the Asia data center, on rack1 and to minimize BW usage
+for inter-datacenter, use the prefer_local
+
+For ``Ec2MultiRegion`` the file should include the following information
+
+.. code-block:: cql
+
+ dc_suffix=my_dc
+
+This will create a suffix for the node location for example:
+
+.. code-block:: cql
+
+ us-east1_my_dc
+
+
+The problem may also arise if you are using some :code:`DC-aware snitch`, e.g. :code:`Ec2MultiRegionSnitch`, and a :code:`SimpleStrategy` in a multi-DC cluster.
+
+Please, make sure that both a snitch and a replication strategy of a keyspace are either both of a :code:`Simple` kind or both are :code:`DC-aware`.
+
+After that, if you are using a :code:`DC-aware` configuration, make sure that the replication strategy uses the proper data centers' names. Verify the data centers names in your cluster using a :code:`nodetool status` command.
+
+Can I change the replication factor (a keyspace) on a live cluster?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, but it will require running a full repair (or cleanup) to change the replica count of existing data:
+
+- :ref:`Alter <alter-keyspace-statement>` the replication factor for desired keyspace (using cqlsh for instance).
+- If you're reducing the replication factor, run ``nodetool cleanup <updated Keyspace>`` on the keyspace you modified to remove surplus replicated data.
+ Cleanup runs on a per-node basis.
+- If you're increasing the replication factor, refer to :doc:`How to Safely Increase the RF </kb/rf-increase>`
+- Note that you need to provide the keyspace namr. If you do not, the cleanup or repair operation runs on all keyspaces for the specific node.
+
+Why can't I set ``listen_address`` to listen to 0.0.0.0 (all my addresses)?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Scylla is a gossip-based distributed system and ``listen_address`` is the address a node tells other nodes to reach
+it at. Telling other nodes "contact me on any of my addresses" is a bad idea; if different nodes in the cluster pick
+different addresses for you, Bad Things happen.
+
+If you don't want to manually specify an IP to ``listen_address`` for each node in your cluster (understandable!), leave
+it blank and Scylla will use ``InetAddress.getLocalHost()`` to pick an address. Then it's up to you or your ops team
+to make things resolve correctly (``/etc/hosts/``, dns, etc).
+
+.. _faq-best-scenario-node-multi-availability-zone:
+
+What is the best scenario to add a node to a multi availability zone (AZ)?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If using three node cluster, with RF=3, each node located on a different availability zone (AZ).
+
+For example:
+
+.. code-block:: shell
+
+ Datacenter: DC1
+ Status=Up/Down
+ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 192.168.1.201 118.82 KB 256 33.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.202 111.82 KB 256 33.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.203 114.82 KB 256 33.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+
+All nodes holds 100% of the data.
+If needed to add a single node to the cluster (scale out), the cluster will become imbalance.
+Because the single additional node will split the tokens only with the existing node in the same AZ.
+
+.. Note::
+
+ This is only an example, if having more nodes or different RF the number of nodes may be different.
+
+
+The token distribution will be:
+
+.. code-block:: shell
+
+ AZ A1 node A: 100% of the data
+ AZ B1 node B: 100% of the data
+ AZ C1 node C: 50% of the data
+ AZ C1 node D: 50% of the data
+
+The solution is to add a node in each AZ.
+
+.. code-block:: shell
+
+ Datacenter: DC1
+ Status=Up/Down
+ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 192.168.1.201 118.82 KB 256 16.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.202 111.82 KB 256 16.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.203 114.82 KB 256 16.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+ UN 192.168.1.204 118.82 KB 256 16.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.205 111.82 KB 256 16.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.206 114.82 KB 256 16.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+
+More info
+---------
+Where can I ask a question not covered here?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Two mailing lists.
+
+* `scylladb-dev <https://groups.google.com/d/forum/scylladb-dev>`_: Discuss the development of Scylla itself.
+* `scylladb-users <https://groups.google.com/d/forum/scylladb-users>`_: Discuss using Scylla and developing client applications.
+
+I deleted data from Scylla, but disk usage stays the same. Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Data you write to Scylla gets persisted to SSTables. Since SSTables are immutable, the data can't actually be removed
+when you perform a delete, instead, a marker (also called a "tombstone") is written to indicate the value's new status.
+Never fear though, on the first compaction that occurs between the data and the tombstone, the data will be expunged
+completely and the corresponding disk space recovered.
+
+What are seeds?
+^^^^^^^^^^^^^^^
+
+Seeds are used during startup to discover the cluster. They are referred by new nodes on bootstrap to learn about other nodes in the ring. When you add a new node to the cluster, you
+must specify one live seed to contact.
+
+In ScyllaDB versions earlier than Scylla Open Source 4.3 and Scylla Enterprise 2021.1, a seed node has an additional
+function: it assists with gossip convergence. See :doc:`Scylla Seed Nodes </kb/seed-nodes/>` for details.
+
+We recommend updating your ScyllaDB to version 4.3 or later (Open Source) or 2021.1 or later (Enterprise).
+
+Does single seed mean single point of failure?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ring can operate or boot without a seed; however, you will not be able to add new nodes to the cluster. It is recommended to configure multiple seeds in production systems.
+
+.. _faq-raid0-required:
+
+Is RAID0 required for Scylla? Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+No, it is not required, but it is highly recommended when using Scylla with more than one drive. Scylla requires one drive for its data file and one drive for commit log (can be the same). If you want to take advantage of more than one drive, the easiest way to do so is set RAID0 (striped) across all of them. If you choose, scylla_setup will setup RAID0 for you on your selected drive, as well as XFS file system (recommended).
+Similarly, Scylla AMI on EC2 will automatically mount all available SSD drives in RAID0.
+
+Should I use RAID for replications, such as RAID1, RAID4 or higher?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can, but it is not recommended. Scylla :doc:`clustering architecture </architecture/ringarchitecture/index/>` already provides data replication across nodes and DCs.
+Adding another layer of replication in each node is redundant, slows down I/O operation and reduces available storage.
+Want a higher level of replication?
+Increase the Replication Factor (RF) of :doc:`relevant Keyspaces </getting-started/ddl/>`.
+
+Can I use JBOD and not use RAID0?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:term:`JBOD` is not supported by Scylla.
+
+:abbr:`JBOD (Just a Bunch Of Disks)` may be a reasonable solution for Cassandra because it rebuilds nodes very slowly. As this is not an issue for Scylla, it's more efficient to use RAID.
+
+Explanation: There are two types of deployment when multiple disks exist. In the JBOD case, each disk is an isolated filesystem. I/O isn't stripped and thus performance can be slower than that of RAID. In addition, as the free space isn't shared, a single disk can be full while the others are available.
+
+The benefit of JBOD vs RAID is that it isolates failures to individual disk and not the entire node.
+However, Scylla rebuilds nodes quickly and thus it is not an issue when rebuilding an entire node.
+
+As a result, it is much more advantageous to use RAID with Scylla
+
+
+Is ``Nodetool Repair`` a Local (One Node) Operation or a Global (Full Cluster) Operation?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When running :doc:`nodetool repair </operating-scylla/nodetool-commands/repair/>` on a node, it performs a repair on every token range this node owns; this will also repair other nodes that share the same range.
+
+If you wish to repair the entire cluster, it is recommended to run ``nodetool repair -pr`` on each node in the cluster, sequentially, or use the :doc:`Scylla Manager </operating-scylla/manager/index/>`.
+
+
+How can I change the maximum number of IN restrictions?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can restrict the number of items in the IN clause with the following options:
+
+* ``--max-partition-key-restrictions-per-query`` - Specifies the maximum number of distinct partition keys restrictions per query. This limit places a bound
+ on the size of IN tuples, especially when multiple partition key columns have IN restrictions. The default is ``100``.
+* ``--max-clustering-key-restrictions-per-query`` - Specifies the maximum number of distinct clustering keys restrictions per query. This limit
+ places a bound on the size of IN tuples, especially when multiple clustering key columns have IN restrictions. The default is ``100``.
+
+.. warning::
+
+ We recommend that you use these options with caution. Changing the maximum number of IN restrictions to more than 100 may result in server instability.
+
+The options can be configured on the command line, passed with ``SCYLLA_ARGS`` in ``/etc/default/scylla-server`` or ``/etc/sysconfig/scylla-server``,
+or added to your ``scylla.yaml`` (see :doc:`Scylla Configuration<operating-scylla/admin>`).
+
+in-memory tables
+----------------
+
+Is MV and SI supported for use with in-memory tables? If so, how will it affect the total memory size limitation?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can make MV table an in-memory, as you would with every other table. It effects the total memory size allocation just like any other table. Make sure before you create any kind of in-memory table that its use case warrants the creation.
+
+Can Scylla Enterprise in-memory tables be used without having a mirror file on disk?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+No. In Scylla Enterprise 2018.1.7, in-memory tables are always persistent using an on-disk mirror file.
+
+What happens if we apply an ``ALTER`` CQL command to change a table from/to in memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It goes in and out of in-memory, as expected. This is :ref:`documented <change-a-table-to-an-in-memory-table>` in the Scylla Docs.
+
+Can I change the coredump mount point?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, by edit ``sysctl.d``.
+
+Procedure
+
+1. Create ``/etc/sysctl.d/99-scylla-coredump.conf`` (this file exists by default in Scylla AMI).
+
+2. Open the ``99-scylla-coredump.conf`` file.
+
+3. Add the following line ``kernel.core_pattern=|/<path>/<coredump_directory> %p %u %g %s %t %e"``
+
+For example:
+
+.. code-block:: shell
+
+ kernel.core_pattern=|/home/centos/core/ %p %u %g %s %t %e"
+
+4. Run ``sysctl -p /etc/sysctl.d/99-scylla-coredump.conf``
+
+Do I need to run a tool like ``upgradesstables`` when moving to a new format?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike Apache Cassandra, Scylla does not ship with upgradesstables, a tool that converts SSTables to newer formats. When upgrading to a new table format, Scylla can still continue to read from the old format. Having this option, ensures a smoother transition and upgrade. New writes use the new format and reads will use both formats until the old tables are removed. If you want to purge all of the old SSTables in a single step, generate a compaction with :doc:`nodetool compact </operating-scylla/nodetool-commands/compact/>` follow by :doc:`nodetool cleanup </operating-scylla/nodetool-commands/cleanup/>` to remove no longer needed token ranges that belong to that node.
+
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/_common/note-io.rst b/docs/getting-started/_common/note-io.rst
--- a/docs/getting-started/_common/note-io.rst
+++ b/docs/getting-started/_common/note-io.rst
@@ -0,0 +1,10 @@
+.. note::
+
+ It's important to keep I/O scheduler configuration in sync on nodes with the same hardware.
+ That's why we recommend skipping running scylla_io_setup when provisioning a new node with exactly the same hardware setup as existing nodes in the cluster.
+
+ Instead, we recommend to copy the following files from an existing node to the new node after running scylla_setup and restart scylla-server service (if it is already running):
+ * /etc/scylla.d/io.conf
+ * /etc/scylla.d/io_properties.yaml
+
+ Using different I/O scheduler configuration may result in unnecessary bottlenecks.
diff --git a/docs/getting-started/_common/note-reclaim-space.rst b/docs/getting-started/_common/note-reclaim-space.rst
--- a/docs/getting-started/_common/note-reclaim-space.rst
+++ b/docs/getting-started/_common/note-reclaim-space.rst
@@ -0,0 +1,2 @@
+.. note:: By default, when a table or a keyspace is removed, a snapshot is taken so that you can restore it later. As a result, the disk space remains the same and is not immediately reclaimed.
+ Refer to :doc:`this article </troubleshooting/drop-table-space-up/>` or this :ref:`FAQ entry<reclaim-space>`.
\ No newline at end of file
diff --git a/docs/getting-started/_common/system-configuration-index.rst b/docs/getting-started/_common/system-configuration-index.rst
--- a/docs/getting-started/_common/system-configuration-index.rst
+++ b/docs/getting-started/_common/system-configuration-index.rst
@@ -0,0 +1,206 @@
+Configure Scylla
+================
+
+System configuration steps are performed automatically by the Scylla RPM and deb packages. For information on getting started with Scylla, see :doc:`Getting Started </getting-started/index>`.
+
+All Scylla AMIs and Docker images are pre-configured by a script with the following steps. This document is provided as a reference.
+
+.. _system-configuration-files-and-scripts:
+
+System Configuration Files and Scripts
+--------------------------------------
+Several system configuration settings should be applied. For ease of use, the necessary scripts and configuration files are provided. Files are under :code:`dist/common` and :code:`seastar/scripts` in the Scylla source code and installed in the appropriate system locations. (For information on Scylla’s own configuration file, see Scylla Configuration.)
+
+.. list-table:: System Configuration Files
+ :widths: 50 50
+ :header-rows: 1
+
+ * - File Name
+ - Description
+ * - scylla.conf
+ - Remove system resource limits
+ * - scylla-server
+ - Server startup options
+ * - (written by ``scylla_coredump_setup``, below)
+ - Configure core dumps to use the ``scylla_save_coredump`` script
+
+Scylla Scripts
+--------------
+
+The following scripts are available for you to run for configuring Scylla. Some of these scripts are included in the scylla_setup script. This script is used for configuring Scylla the first time, or when the system hardware changes.
+
+
+.. list-table:: Scylla Setup Scripts
+ :widths: 40 60
+ :header-rows: 1
+
+ * - perftune.py
+ - Configures various system parameters in order to improve the Seastar application performance
+ * - scylla_bootparam_setup
+ - Sets the kernel options in the bootloader. In addition, it tunes Linux boot-time parameters for the node that Scylla is running on (e.g. huge page setup).
+ * - scylla_coredump_setup
+ - Sets up coredump facilities for Scylla. This may include uninstalling existing crash reporting software for compatibility reasons.
+ * - scylla_io_setup
+ - Benchmarks the disks and generates the io.conf and io_properties.yaml files.
+ * - scylla_ntp_setup
+ - Configures Network Time Protocol
+ * - scylla_prepare
+ - This script is run automatically every time Scylla starts and the machine needs to be tuned.
+ * - scylla_raid_setup
+ - Configures RAID and makes an XFS filesystem.
+ * - scylla_save_coredump
+ - Compresses a core dump file (Ubuntu only)
+ * - scylla_setup
+ - Sets up the Scylla configuration. Many of these scripts are included in the setup script.
+ * - scylla_stop
+ - Resets network mode if running in virtio or DPDK mode.
+ * - scylla_swap_setup
+ - Configures a swap space on the host.
+ * - scylla_sysconfig_setup
+ - Rewrites the /etc/sysconfig/scylla file.
+
+
+.. list-table:: Scylla Scripts (Not included with Scylla-Setup)
+ :widths: 40 60
+ :header-rows: 1
+
+ * - Script Name
+ - Description
+ * - node_health_check
+ - Gathers metrics and information on the node, checking that the node is configured correctly.
+ * - scylla-blocktune
+ - Tunes the filesystem and block layer (e.g. block size I/O scheduler configuration) for Scylla.
+ * - scylla_cpuscaling_setup
+ - Configures the CPU frequency scaling (IOW, puts the CPU in "performance" mode, instead of the slower "powersave" mode).
+ * - scylla_cpuset_setup
+ - Configures which CPUs the Scylla server threads run on.
+ * - scylla_fstrim
+ - Runs ``fstrim``, which cleans up unused blocks of data from your SSD storage device. It runs automatically if you run scylla_fstrim_set up (see below).
+ * - scylla_fstrim_setup
+ - Configures a job so that ``fstrim`` runs automatically.
+ * - scylla-housekeeping
+ - Checks if there are new versions of Scylla available, and also shares some telemetry information for us to keep track of what versions are installed on the field.
+ * - scylla_rsyslog_setup
+ - Configures the "rsyslog" service, which is used to send logs to a remote server.
+ * - scylla_selinux_setup
+ - Disables SELinux for Scylla.
+
+.. _note-io:
+
+.. include:: /getting-started/_common/note-io.rst
+
+Bootloader Settings
+-------------------
+If Scylla is installed on an Amazon AMI, the bootloader should provide the :code:`clocksource=tsc` and :code:`tsc=reliable` options. This enables an accurate, high-resolution `Time Stamp Counter (TSC) <https://software.intel.com/en-us/blogs/2013/06/20/eliminate-the-dreaded-clocksource-is-unstable-message-switch-to-tsc-for-a-stable>`_ for setting the system time.
+
+This configuration is provided in the file :code:`/usr/lib/scylla/scylla_bootparam_setup`.
+
+Remove Crash Reporting Software
+-------------------------------
+Remove the :code:`apport-noui` or :code:`abrt` packages if present, and set up a location and file name pattern for core dumps.
+
+This configuration is provided in the file :code:`/usr/lib/scylla/scylla_bootparam_setup`.
+
+Set Up Network Time Synchronization
+-----------------------------------
+It is highly recommended to enforce time synchronization between Scylla servers.
+
+Run :code:`ntpstat` on all nodes to check that system time is synchronized. If you are running in a virtualized environment and your system time is set on the host, you may not need to run NTP on the guest. Check the documentation for your platform.
+
+If you have your own time servers shared with an application using Scylla, use the same NTP configuration as for your application servers. The script :code:`/usr/lib/scylla/scylla_ntp_setup` provides sensible defaults, using Amazon NTP servers if installed on the Amazon cloud, and other pool NTP servers otherwise.
+
+Set Up RAID and Filesystem
+--------------------------
+Setting the file system to XFS is the most important and mandatory for production. Scylla will significantly slow down without it.
+
+The script :code:`/usr/lib/scylla/scylla_raid_setup` performs the necessary RAID configuration and XFS filesystem creation for Scylla.
+
+Arguments to the script are
+
+* :code:`-d` specify disks for RAID
+* :code:`-r` MD device name for RAID
+* :code:`-u` update /etc/fstab for RAID
+
+On the Scylla AMI, the RAID configuration is handled automatically in the :code:`/usr/lib/scylla/scylla_prepare script`.
+
+CPU Pinning
+-----------
+
+When installing Scylla, it is highly recommended to use the :doc:`scylla_setup </getting-started/system-configuration>` script.
+Scylla should not share CPUs with any CPU consuming process. In addition, when running Scylla on AWS, we recommend pinning all NIC IRQs to CPU0 (due to the same reason). As a result, Scylla should be prevented from running on CPU0 and its hyper-threading siblings. To verify that Scylla is pinning CPU0, use the command below:
+If the node has four or fewer CPUs, don't use this option.
+
+To verify:
+
+.. code-block:: shell
+
+ cat /etc/scylla.d/cpuset.conf
+
+
+Example output:
+
+.. code-block:: shell
+
+ --cpuset `1-15,17-31`
+
+Networking
+----------
+On AWS:
+^^^^^^^
+1. Prevent irqbalance from moving your NICs’ IRQs.
+2. Bind all NICs’ HW queues to CPU0:
+
+.. code-block:: shell
+
+ for irq in `cat /proc/interrupts | grep <networking iface name> | cut -d":" -f1`
+ do echo "Binding IRQ $irq to CPU0" echo 1 > /proc/irq/$irq/smp_affinity done
+
+3. Enable RPS and bind RPS queues to CPUs other than CPU0 and its hyper-threading siblings.
+4. Enable XPS and distribute all XPS queues among all available CPUs.
+
+The `posix_net_conf.sh <https://github.com/scylladb/seastar/blob/master/scripts/posix_net_conf.sh>`_ script does all of the above.*
+
+On Bare Metal Setups with Multi-Queue NICs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+1. Prevent irqbalance from moving your NICs IRQs.
+2. Bind each NIC’s IRQ to a separate CPU.
+3. Enable XPS exactly the same way as for AWS above.
+4. Set higher values for a listen() socket backlog and for unacknowledged pending connections backlog:
+
+.. code-block:: shell
+
+ echo 4096 > /proc/sys/net/core/somaxconn
+ echo 4096 > /proc/sys/net/ipv4/tcp_max_syn_backlog
+
+The `posix_net_conf.sh <https://github.com/scylladb/seastar/blob/master/scripts/posix_net_conf.sh>`_ script with the :code:`-mq` parameter does all of the above.
+
+Configuring Scylla
+------------------
+Configuration for Scylla itself is in the :ref:`Scylla Configuration <admin-scylla-configuration>` section of the administration guide.
+
+Development System Configuration
+--------------------------------
+*The following item is not required in production.*
+
+When working on DPDK support for Scylla, enable hugepages.
+
+.. code-block:: shell
+
+ NR_HUGEPAGES=128
+ mount -t hugetlbfs -o pagesize=2097152 none /mnt/huge
+ mount -t hugetlbfs -o pagesize=2097152 none /dev/hugepages/
+ for n in /sys/devices/system/node/node?; do
+ echo $NR_HUGEPAGES > $n/hugepages/hugepages-2048kB/nr_hugepages;
+ done
+
+Huge page configuration is written to :code:`/etc/sysconfig/scylla-server` by the script :code:`/usr/lib/scylla/sysconfig_setup`
+
+
+
+
+Related Topics
+--------------
+
+:doc:`System Limits </kb/system-limits>` - outlines the system limits which should be set or removed.
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/appendices.rst b/docs/getting-started/appendices.rst
--- a/docs/getting-started/appendices.rst
+++ b/docs/getting-started/appendices.rst
@@ -0,0 +1,317 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+Appendices
+----------
+
+.. include:: /rst_include/cql-version-index.rst
+
+.. _appendix-A:
+
+Appendix A: CQL Keywords
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+CQL distinguishes between *reserved* and *non-reserved* keywords.
+Reserved keywords cannot be used as an identifier. They are truly reserved
+for the language (but one can enclose a reserved keyword by
+double-quotes to use it as an identifier). Non-reserved keywords, however,
+only have a specific meaning in a certain context but can be used as
+identifiers otherwise. The only *raison d’être* of these non-reserved
+keywords is convenience: some keyword are non-reserved when it was
+always easy for the parser to decide whether they were used as keywords
+or not.
+
++--------------------+-------------+
+| Keyword | Reserved? |
++====================+=============+
+| ``ADD`` | yes |
++--------------------+-------------+
+| ``AGGREGATE`` | no |
++--------------------+-------------+
+| ``ALL`` | no |
++--------------------+-------------+
+| ``ALLOW`` | yes |
++--------------------+-------------+
+| ``ALTER`` | yes |
++--------------------+-------------+
+| ``AND`` | yes |
++--------------------+-------------+
+| ``APPLY`` | yes |
++--------------------+-------------+
+| ``AS`` | no |
++--------------------+-------------+
+| ``ASC`` | yes |
++--------------------+-------------+
+| ``ASCII`` | no |
++--------------------+-------------+
+| ``AUTHORIZE`` | yes |
++--------------------+-------------+
+| ``BATCH`` | yes |
++--------------------+-------------+
+| ``BEGIN`` | yes |
++--------------------+-------------+
+| ``BIGINT`` | no |
++--------------------+-------------+
+| ``BLOB`` | no |
++--------------------+-------------+
+| ``BOOLEAN`` | no |
++--------------------+-------------+
+| ``BY`` | yes |
++--------------------+-------------+
+| ``CALLED`` | no |
++--------------------+-------------+
+| ``CLUSTERING`` | no |
++--------------------+-------------+
+| ``COLUMNFAMILY`` | yes |
++--------------------+-------------+
+| ``COMPACT`` | no |
++--------------------+-------------+
+| ``CONTAINS`` | no |
++--------------------+-------------+
+| ``COUNT`` | no |
++--------------------+-------------+
+| ``COUNTER`` | no |
++--------------------+-------------+
+| ``CREATE`` | yes |
++--------------------+-------------+
+| ``CUSTOM`` | no |
++--------------------+-------------+
+| ``DATE`` | no |
++--------------------+-------------+
+| ``DECIMAL`` | no |
++--------------------+-------------+
+| ``DELETE`` | yes |
++--------------------+-------------+
+| ``DESC`` | yes |
++--------------------+-------------+
+| ``DESCRIBE`` | yes |
++--------------------+-------------+
+| ``DISTINCT`` | no |
++--------------------+-------------+
+| ``DOUBLE`` | no |
++--------------------+-------------+
+| ``DROP`` | yes |
++--------------------+-------------+
+| ``ENTRIES`` | yes |
++--------------------+-------------+
+| ``EXECUTE`` | yes |
++--------------------+-------------+
+| ``EXISTS`` | no |
++--------------------+-------------+
+| ``FILTERING`` | no |
++--------------------+-------------+
+| ``FINALFUNC`` | no |
++--------------------+-------------+
+| ``FLOAT`` | no |
++--------------------+-------------+
+| ``FROM`` | yes |
++--------------------+-------------+
+| ``FROZEN`` | no |
++--------------------+-------------+
+| ``FULL`` | yes |
++--------------------+-------------+
+| ``FUNCTION`` | no |
++--------------------+-------------+
+| ``FUNCTIONS`` | no |
++--------------------+-------------+
+| ``GRANT`` | yes |
++--------------------+-------------+
+| ``IF`` | yes |
++--------------------+-------------+
+| ``IN`` | yes |
++--------------------+-------------+
+| ``INDEX`` | yes |
++--------------------+-------------+
+| ``INET`` | no |
++--------------------+-------------+
+| ``INFINITY`` | yes |
++--------------------+-------------+
+| ``INITCOND`` | no |
++--------------------+-------------+
+| ``INPUT`` | no |
++--------------------+-------------+
+| ``INSERT`` | yes |
++--------------------+-------------+
+| ``INT`` | no |
++--------------------+-------------+
+| ``INTO`` | yes |
++--------------------+-------------+
+| ``JSON`` | no |
++--------------------+-------------+
+| ``KEY`` | no |
++--------------------+-------------+
+| ``KEYS`` | no |
++--------------------+-------------+
+| ``KEYSPACE`` | yes |
++--------------------+-------------+
+| ``KEYSPACES`` | no |
++--------------------+-------------+
+| ``LANGUAGE`` | no |
++--------------------+-------------+
+| ``LIMIT`` | yes |
++--------------------+-------------+
+| ``LIST`` | no |
++--------------------+-------------+
+| ``LOGIN`` | no |
++--------------------+-------------+
+| ``MAP`` | no |
++--------------------+-------------+
+| ``MODIFY`` | yes |
++--------------------+-------------+
+| ``NAN`` | yes |
++--------------------+-------------+
+| ``NOLOGIN`` | no |
++--------------------+-------------+
+| ``NORECURSIVE`` | yes |
++--------------------+-------------+
+| ``NOSUPERUSER`` | no |
++--------------------+-------------+
+| ``NOT`` | yes |
++--------------------+-------------+
+| ``NULL`` | yes |
++--------------------+-------------+
+| ``OF`` | yes |
++--------------------+-------------+
+| ``ON`` | yes |
++--------------------+-------------+
+| ``OPTIONS`` | no |
++--------------------+-------------+
+| ``OR`` | yes |
++--------------------+-------------+
+| ``ORDER`` | yes |
++--------------------+-------------+
+| ``PASSWORD`` | no |
++--------------------+-------------+
+| ``PERMISSION`` | no |
++--------------------+-------------+
+| ``PERMISSIONS`` | no |
++--------------------+-------------+
+| ``PRIMARY`` | yes |
++--------------------+-------------+
+| ``RENAME`` | yes |
++--------------------+-------------+
+| ``REPLACE`` | yes |
++--------------------+-------------+
+| ``RETURNS`` | no |
++--------------------+-------------+
+| ``REVOKE`` | yes |
++--------------------+-------------+
+| ``ROLE`` | no |
++--------------------+-------------+
+| ``ROLES`` | no |
++--------------------+-------------+
+| ``SCHEMA`` | yes |
++--------------------+-------------+
+| ``SELECT`` | yes |
++--------------------+-------------+
+| ``SET`` | yes |
++--------------------+-------------+
+| ``SFUNC`` | no |
++--------------------+-------------+
+| ``SMALLINT`` | no |
++--------------------+-------------+
+| ``STATIC`` | no |
++--------------------+-------------+
+| ``STORAGE`` | no |
++--------------------+-------------+
+| ``STYPE`` | no |
++--------------------+-------------+
+| ``SUPERUSER`` | no |
++--------------------+-------------+
+| ``TABLE`` | yes |
++--------------------+-------------+
+| ``TEXT`` | no |
++--------------------+-------------+
+| ``TIME`` | no |
++--------------------+-------------+
+| ``TIMESTAMP`` | no |
++--------------------+-------------+
+| ``TIMEUUID`` | no |
++--------------------+-------------+
+| ``TINYINT`` | no |
++--------------------+-------------+
+| ``TO`` | yes |
++--------------------+-------------+
+| ``TOKEN`` | yes |
++--------------------+-------------+
+| ``TRIGGER`` | no |
++--------------------+-------------+
+| ``TRUNCATE`` | yes |
++--------------------+-------------+
+| ``TTL`` | no |
++--------------------+-------------+
+| ``TUPLE`` | no |
++--------------------+-------------+
+| ``TYPE`` | no |
++--------------------+-------------+
+| ``UNLOGGED`` | yes |
++--------------------+-------------+
+| ``UPDATE`` | yes |
++--------------------+-------------+
+| ``USE`` | yes |
++--------------------+-------------+
+| ``USER`` | no |
++--------------------+-------------+
+| ``USERS`` | no |
++--------------------+-------------+
+| ``USING`` | yes |
++--------------------+-------------+
+| ``UUID`` | no |
++--------------------+-------------+
+| ``VALUES`` | no |
++--------------------+-------------+
+| ``VARCHAR`` | no |
++--------------------+-------------+
+| ``VARINT`` | no |
++--------------------+-------------+
+| ``WHERE`` | yes |
++--------------------+-------------+
+| ``WITH`` | yes |
++--------------------+-------------+
+| ``WRITETIME`` | no |
++--------------------+-------------+
+
+Appendix B: CQL Reserved Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following type names are not currently used by CQL but are reserved
+for potential future use. User-defined types may not use reserved type
+names as their name.
+
++-----------------+
+| type |
++=================+
+| ``bitstring`` |
++-----------------+
+| ``byte`` |
++-----------------+
+| ``complex`` |
++-----------------+
+| ``enum`` |
++-----------------+
+| ``interval`` |
++-----------------+
+| ``macaddr`` |
++-----------------+
+
+
+
+.. include:: /rst_include/apache-copyrights-index.rst
+.. include:: /rst_include/apache-cql-return-index.rst
diff --git a/docs/getting-started/checkmark-16.png b/docs/getting-started/checkmark-16.png
--- a/docs/getting-started/checkmark-16.png
+++ b/docs/getting-started/checkmark-16.png
null
diff --git a/docs/getting-started/compaction.rst b/docs/getting-started/compaction.rst
--- a/docs/getting-started/compaction.rst
+++ b/docs/getting-started/compaction.rst
@@ -0,0 +1,352 @@
+
+.. _compaction:
+
+Compaction
+----------
+
+
+This document describes the compaction strategy options available when creating a table. For more information about creating a table in Scylla, refer to the :ref:`CQL Reference <create-table-statement>`.
+
+By default, Scylla starts a compaction task whenever a new SSTable is written. Compaction merges several SSTables into a new SSTable, which contains only the live data from the input SSTables. Merging several sorted files to get a sorted result is an efficient process, and this is the main reason why SSTables are kept sorted.
+
+The following compaction strategies are supported by Scylla:
+
+* Size-tiered Compaction Strategy (`STCS`_)
+
+* Leveled Compaction Strategy (`LCS`_)
+
+* Incremental Compaction Strategy (`ICS`_)
+
+* Time-window Compaction Strategy (`TWCS`_)
+
+* Date-tiered Compaction Strategy (DTCS) - use `TWCS`_ instead
+
+This page concentrates on the parameters to use when creating a table with a compaction strategy. If you are unsure which strategy to use or want general information on the compaction strategies which are available to Scylla, refer to :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>`.
+
+Common options
+^^^^^^^^^^^^^^
+The following options are available for all compaction strategies.
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'compaction_strategy_name',
+ 'enabled' : (true | false),
+ 'tombstone_threshold' : ratio,
+ 'tombstone_compaction_interval' : sec}
+
+
+
+``class`` (default: SizeTieredCompactionStrategy)
+ Selects the compaction strategy.
+
+ It can be one of the following. If you are unsure which one to choose, refer to :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>` :
+
+ * SizeTieredCompactionStrategy
+ * TimeWindowCompactionStrategy
+ * LeveledCompactionStrategy
+
+
+=====
+
+``enabled`` (default: true)
+ Runs background compaction (known as “minor compaction”). Can be one of the following:
+
+ * true - runs minor compaction
+ * false - disable minor compaction
+
+=====
+
+``tombstone_threshold`` (default: 0.2)
+ The ratio (expressed as a decimal) of garbage-collectable tombstones compared to the data. When this threshold is exceeded on a specific table, a single SSTable compaction begins. Acceptable values are numbers in the range 0 -1.
+
+=====
+
+``tombstone_compaction_interval`` (default: 86400s (1 day))
+ An SSTable that is suitable for single SSTable compaction, according to tombstone_threshold will not be compacted if it is newer than tombstone_compaction_interval.
+
+=====
+
+.. _STCS:
+
+Size Tiered Compaction Strategy (STCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When using STCS, SSTables are put in different buckets depending on their size. When an SSTable is bucketed, the average size of the tables is compared to the new table as well as the high and low threshold levels.
+
+The database compares each SSTable size to the average of all SSTable sizes on the node. It calculates ``bucket_low * avg_bucket_size`` and ``bucket_high * avg_bucket_size`` and then compares the result with the average SSTable size. The conditions set for ``bucket_high`` and ``bucket_low`` dictate if successive tables will be added to the same bucket. When compaction begins it merges SSTables whose size in KB are within ``[average-size * bucket_low]`` and ``[average-size * bucket_high]``.
+
+Once the ``min_threashold`` is reached, minor compaction begins.
+
+.. _stcs-options:
+
+STCS options
+~~~~~~~~~~~~
+
+The following options only apply to SizeTieredCompactionStrategy:
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'SizeTieredCompactionStrategy',
+ 'bucket_high' : factor,
+ 'bucket_low' : factor,
+ 'min_sstable_size' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables}
+
+``bucket_high`` (default: 1.5)
+ A new SSTable is added to the bucket if the SSTable size is less than bucket_high * the average size of that bucket (and if the bucket_low condition also holds).
+
+ For example, if **'bucket_high = 1.5'** and the **SSTable size = 14MB**, does it belong to a bucket with an average size of 10MB?
+
+ Yes, because the **SSTable size = 14`**, which is **less** than **'bucket_high' * average bucket size = 15**.
+
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``bucket_low`` (default: 0.5)
+ A new SSTable is added to the bucket if the SSTable size is more than bucket_low* the average size of that bucket (and if the bucket_high condition also holds).
+
+ For example, if **'bucket_high = 0.5'** and the **SSTable size is 10MB**, does it belong to a bucket with an average size is 15MB?
+
+ Yes, because the **SSTable size = 10** which is **more** than **'bucket_low' * average bucket size = 7.5**.
+
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``min_sstable_size`` (default: 50)
+ All SSTables smaller than this number of bytes are put into the same bucket.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTables that need to belong to the same size bucket before compaction is triggered on that bucket.
+ If your SSTables are small, use *min_sstable_size* to define a size threshold (in bytes) below which all SSTables belong to one unique bucket.
+
+ .. note:: Enforcement of ``min_threshold`` is controlled by the ``compaction_enforce_min_threshold`` configuration option in the scylla.yaml configuration settings.
+ By default, ``compaction_enforce_min_threshold: false``, meaning the Size-Tiered Compaction Strategy will compact any bucket containing 2 or more SSTables.
+ Otherwise, if ``compaction_enforce_min_threshold: true``, the value of ``min_threshold`` is considered and only those buckets that contain at
+ least ``min_threshold`` SSTables will be compacted.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+
+
+.. _LCS:
+
+Leveled Compaction Strategy (LCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compaction class LeveledCompactionStrategy (LCS) creates SSTables of a fixed, relatively small size (160 MB by default) that are grouped into levels. Within each level, SSTables are guaranteed to be non-overlapping. Each level (L0, L1, L2 and so on) is ten times as large as the previous level.
+
+.. _lcs-options:
+
+LCS options
+~~~~~~~~~~~
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'LeveledCompactionStrategy',
+ 'sstable_size_in_mb' : int}
+
+``sstable_size_in_mb`` (default: 160)
+ This is the target size in megabytes, that will be used as the goal for an SSTable size following a compression.
+ Although SSTable sizes should be less or equal to sstable_size_in_mb, it is possible that compaction could produce a larger SSTable during compaction. This occurs when data for a given partition key is exceptionally large.
+
+=====
+
+.. _ICS:
+
+Incremental Compaction Strategy (ICS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. note:: ICS is only available for Scylla Enterprise customers
+
+When using ICS, SSTable runs are put in different buckets depending on their size.
+When an SSTable run is bucketed, the average size of the runs in the bucket is compared to the new run, as well as the ``bucket_high`` and ``bucket_low`` levels.
+
+
+The database compares each SSTable-run size to the average of all SSTable-run sizes on all buckets in the node.
+It calculates ``bucket_low * avg_bucket_size`` and ``bucket_high * avg_bucket_size`` and then compares the result with the ``average SSTable-run size``.
+The conditions set for ``bucket_high`` and ``bucket_low`` dictate if successive runs will be added to the same bucket.
+When compaction begins it merges SSTable runs whose size in KB are within ``[average-size * bucket_low]`` and ``[average-size * bucket_high]``.
+
+
+Once there are multiple runs in a bucket, minor compaction begins.
+The minimum number of SSTable runs that triggers minor compaction is either 2 or ``min_threshold``, if the ``compaction_enforce_min_threshold``
+configuration option is set in the scylla.yaml configuration file.
+
+.. _ics-options:
+
+ICS options
+~~~~~~~~~~~~
+
+The following options only apply to IncrementalCompactionStrategy:
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'IncrementalCompactionStrategy',
+ 'bucket_high' : factor,
+ 'bucket_low' : factor,
+ 'min_sstable_size' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables,
+ 'sstable_size_in_mb' : int,
+ 'space_amplification_goal' : double}
+
+=====
+
+``bucket_high`` (default: 1.5)
+ A new SSTable is added to the bucket if the SSTable size is **less than**
+ bucket_high * the average size of that bucket (and if the bucket_low condition also holds).
+ For example, if **'bucket_high = 1.5'** and the **SSTable size = 14MB**, does the SSTable belong to a bucket with an average size of 10MB?
+ Yes, because the **SSTable size = 14**, which is **less** than **'bucket_high' * average bucket size = 15**.
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``bucket_low`` (default: 0.5)
+ A new SSTable is added to the bucket if the SSTable size is **more than**
+ bucket_low * the average size of that bucket (and if the bucket_high condition also holds).
+ For example, if **'bucket_high = 0.5'** and the **SSTable size is 10MB**, does the SSTable belong to a bucket with an average size of 15MB?
+ Yes, because the **SSTable size = 10**, which is **more** than **'bucket_low' * average bucket size = 7.5**.
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``min_sstable_size`` (default: 50)
+ All SSTables smaller than this number of megabytes are put into the same bucket.
+
+ Unlike Apache Cassandra, scylla uses **uncompressed** size when bucketing similar-sized tiers together.
+ Since compaction works on uncompressed data, SSTables containing similar amounts of data should be compacted together, even when they have different compression ratios.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTable runs that need to belong to the same size bucket before compaction is triggered on that bucket.
+
+ .. note:: Enforcement of ``min_threshold`` is controlled by the ``compaction_enforce_min_threshold`` configuration option in the scylla.yaml configuration settings.
+ By default, ``compaction_enforce_min_threshold=false``, meaning the Incremental Compaction Strategy will compact any bucket containing 2 or more SSTable runs.
+ Otherwise, if ``compaction_enforce_min_threshold=true``, the value of ``min_threshold`` is considered and only those buckets that contain at
+ least ``min_threshold`` SSTable runs will be compacted.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+=====
+
+``sstable_size_in_mb`` (default: 1000)
+ This is the target size in megabytes, that will be used as the goal for an SSTable size (fragment size) following a compression.
+
+.. _SAG:
+
+=====
+
+``space_amplification_goal`` (default: null)
+
+.. versionadded:: 2020.1.6 Scylla Enterprise
+
+ This is a threshold of the ratio of the sum of the sizes of the two largest tiers to the size of the largest tier,
+ above which ICS will automatically compact the second largest and largest tiers together to eliminate stale data that may have been overwritten, expired, or deleted.
+ The space_amplification_goal is given as a double-precision floating point number that must be greater than 1.0.
+
+ For example, if **'space_amplification_goal = 1.25'** and the largest tier holds **1000GB**,
+ when the second-largest tier accumulates SSTables with the total size of 250GB or more,
+ the ``space_amplification_goal`` threshold is crossed and all the SSTables in the largest and second-largest tiers will be compacted together.
+
+=====
+
+.. _TWCS:
+
+Time Window CompactionStrategy (TWCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The basic concept is that TimeWindowCompactionStrategy will create 1 SSTable per file for a given time window.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+.. _twcs-options:
+
+TWCS options
+~~~~~~~~~~~~
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'TimeWindowCompactionStrategy',
+ 'compaction_window_unit' : string,
+ 'compaction_window_size' : int,
+ 'expired_sstable_check_frequency_seconds' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables}
+
+``compaction_window_unit`` (default: DAYS)
+ A time unit used to determine the window size which can be one of the following:
+
+ * ``'MINUTES'``
+
+ * ``'HOURS'``
+
+ * ``'DAYS'``
+
+=====
+
+``compaction_window_size`` (default: 1)
+ The number of units which will make up a window.
+
+=====
+
+``expired_sstable_check_frequency_seconds`` (default: 600)
+ Specifies (in seconds) how often Scylla will check for fully expired SSTables, which can be immediately dropped.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTables that need to belong to the same size bucket before compaction is triggered on that bucket.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+=====
+
+See Also
+^^^^^^^^^
+
+* :doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+* :doc:`Compaction Strategies </architecture/compaction/compaction-strategies/>`
+
+* :doc:`Compaction Overview </kb/compaction>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
diff --git a/docs/getting-started/configure.rst b/docs/getting-started/configure.rst
--- a/docs/getting-started/configure.rst
+++ b/docs/getting-started/configure.rst
@@ -0,0 +1,23 @@
+Configure Scylla
+================
+
+.. raw:: html
+
+ <div class="panel callout radius animated">
+ <div class="row">
+ <div class="medium-3 columns">
+ <h5 id="getting-started">Configure Scylla</h5>
+ </div>
+ <div class="medium-9 columns">
+
+.. include:: /rst_include/configure-index.rst
+
+
+.. raw:: html
+
+ </div>
+ </div>
+ </div>
+
+
+
diff --git a/docs/getting-started/consistency-calculator.html b/docs/getting-started/consistency-calculator.html
--- a/docs/getting-started/consistency-calculator.html
+++ b/docs/getting-started/consistency-calculator.html
@@ -0,0 +1,105 @@
+ <style>
+ .calculator {
+ width: fit-content;
+ }
+ .form-inline {
+ display: flex;
+ flex-flow: row wrap;
+ }
+ .form-inline label {
+ margin: 5px 10px 5px 0;
+ }
+ .form-inline input {
+ padding: 10px;
+ margin: 5px 10px 5px 0;
+ }
+ </style>
+ <div class="calculator">
+ <form class="form-inline" action="">
+ <div class="input">
+ <label for="nodes">Nodes</label><input style="width: 8ch;" type="number" min="1" value="3" name="nodes" id="nodes">
+ </div>
+ <div class="input">
+ <label for="replication-factor">Replication factor</label><input style="width: 8ch;" min="1" value="3" type="number" name="replication-factor" id="replication-factor">
+ </div>
+ <div class="input">
+ <label for="read-consistency">Read consistency level</label><select name="read-consistency" id="read-consistency">
+ <option value="ONE">ONE</option>
+ <option value="TWO">TWO</option>
+ <option value="THREE">THREE</option>
+ <option value="QUORUM">QUORUM</option>
+ <option value="ALL">ALL</option>
+ </select>
+ </div>
+ <div class="input">
+ <label for="write-consistency">Write consistency level</label><select name="write-consistency" id="write-consistency">
+ <option value="ONE">ONE</option>
+ <option value="TWO">TWO</option>
+ <option value="THREE">THREE</option>
+ <option value="QUORUM">QUORUM</option>
+ <option value="ALL">ALL</option>
+ </select>
+ </div>
+ </form>
+ <div class="results"></div>
+ </div>
+
+ <script>
+ function consistency(c, rf) {
+ switch(c) {
+ case "ONE":
+ return 1;
+ case "TWO":
+ return 2;
+ case "THREE":
+ return 3;
+ case "QUORUM":
+ return Math.floor(rf / 2) + 1;
+ case "ALL":
+ return rf;
+ }
+ }
+
+ function calculate() {
+ const nodes = Number.parseInt(document.querySelector("#nodes").value);
+ const readConsistency = document.querySelector("#read-consistency").value;
+ const writeConsistency = document.querySelector("#write-consistency").value;
+ const replicationFactor = document.querySelector("#replication-factor").value;
+ const writeConsistencyN = consistency(writeConsistency, replicationFactor);
+ const readConsistencyN = consistency(readConsistency, replicationFactor);
+
+
+ const resultsDiv = document.querySelector(".results");
+
+ if (nodes < replicationFactor) {
+ resultsDiv.textContent = "Replication factor must be smaller or equal to the number of nodes";
+ resultsDiv.classList.add("warning", "admonition");
+ } else if (writeConsistencyN > replicationFactor || readConsistencyN > replicationFactor) {
+ resultsDiv.textContent = "Consistency level must be lower than replication factor";
+ resultsDiv.classList.add("warning", "admonition");
+ } else {
+ const msg = [];
+ if (writeConsistencyN + readConsistencyN > replicationFactor) {
+ msg.push("Your reads are <b>consistent</b>");
+ } else {
+ msg.push("Your reads are <b>eventually consistent</b>");
+ }
+ msg.push(`You can lose ${replicationFactor - readConsistencyN} nodes without failing reads`);
+ msg.push(`You can lose ${writeConsistencyN - 1} nodes without data loss`);
+ msg.push(`Each node holds ~ ${Math.round(replicationFactor / nodes * 100)}% of your data`);
+
+ resultsDiv.classList.remove("warning", "admonition");
+ resultsDiv.innerHTML = msg.join("<br/>");
+ }
+ }
+
+ document.querySelectorAll(".input input").forEach((element) => {
+ element.addEventListener("input", calculate);
+ })
+
+ document.querySelectorAll(".input select").forEach((element) => {
+ element.addEventListener("input", calculate);
+ })
+
+ calculate();
+ </script>
diff --git a/docs/getting-started/consistency.rst b/docs/getting-started/consistency.rst
--- a/docs/getting-started/consistency.rst
+++ b/docs/getting-started/consistency.rst
@@ -0,0 +1,128 @@
+==================
+Consistency Levels
+==================
+
+
+A :term:`Consistency Level (CL)` is a dynamic value which dictates the number of replicas (in a cluster) that must acknowledge a read or write operation in order for the coordinator node to determine the operation was successful.
+CLs can be used with any transaction including LWTs.
+
+This value is set by the client on a per operation basis. For the CQL Shell, the consistency level defaults to ONE for read and write operations.
+If there is a conflict in settings, the CQLSH setting supersedes a consistency level global setting.
+
+
+Syntax
+------
+.. code-block:: cql
+
+ CONSISTENCY <consistency level>
+
+Examples
+========
+
+Set CONSISTENCY to force the majority of the nodes to respond:
+
+.. code-block:: cql
+
+ CONSISTENCY QUORUM
+
+Set level to serial for LWT read requests:
+
+.. code-block:: cql
+
+ CONSISTENCY SERIAL
+
+Consistency level set to SERIAL.
+
+.. _consistency-levels-reference:
+
+Consistency Levels Reference
+============================
+
+The following table describes the different levels you can set.
+
+.. list-table::
+ :widths: 25 25 25 25
+ :header-rows: 1
+
+ * - Consistency Level
+ - Which Replicas Must Respond
+ - Consistency
+ - Availability
+ * - ANY (Write Only)
+ - Closest replica, as determined by the snitch. If all replica nodes are down, write succeeds after a :term:`hinted handoff`. Provides low latency, guarantees writes never fail.
+ - Lowest (WRITE)
+ - Highest (WRITE)
+ * - ONE
+ - The closest replica as determined by the :term:`Snitch`. Consistency requirements are not too strict.
+ - Lowest (READ)
+ - Highest (READ)
+ * - TWO
+ - The closest two replicas as determined by the Snitch.
+ -
+ -
+ * - THREE
+ - The closest three replicas as determined by the Snitch.
+ -
+ -
+ * - QUORUM
+ - A simple majority of all replicas across all datacenters. This CL allows for some level of failure
+ -
+ -
+ * - LOCAL_QUORUM
+ - Same as QUORUM, but confined to the same datacenter as the coordinator.
+ - Low in multi-data centers
+ -
+ * - ALL
+ - *All* replicas in the cluster
+ - Highest
+ - Lowest (may cause performance issues)
+ * - EACH_QUORUM (Write Only)
+ - A simple majority in each datacenter.
+ - Same across the datacenters.
+ -
+ * - LOCAL_ONE
+ - Same as ONE, but confined to the local datacenter.
+ -
+ -
+ * - SERIAL
+ - Returns results with the most recent data. Including uncommitted in-flight LWTs. Writes are not supported, but read transactions are supported.
+ - Linearizable
+ -
+ * - LOCAL_SERIAL
+ - Same as SERIAL, but confined to a local datacenter. Writes are not supported, but read transactions are supported.
+ - Linearizable for the local DC
+ -
+
+
+Display the Current CL in CQLSh
+-------------------------------
+
+To display your current CL in your CQLsh session, use the CONSISTENCY Command with no options.
+
+.. code-block:: cql
+
+ CONSISTENCY
+
+
+returns
+
+.. code-block:: cql
+
+ Current consistency level is ALL.
+
+
+Consistency level calculator
+----------------------------
+
+.. raw:: html
+ :file: consistency-calculator.html
+
+
+Additional Information
+----------------------
+
+* :doc:`Fault Tolerance </architecture/architecture-fault-tolerance/>`
+* :doc:`Cluster membership changes and LWT consistency </operating-scylla/procedures/cluster-management/membership-changes/>`
+* :ref:`Consistency Level Compatibility <consistency-level-read-and-write>`
+* :doc:`Consistency Quiz </kb/quiz-administrators/>`
+* Take a course on `Consistency Levels at Scylla University <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability/topic/consistency-level/>`_
diff --git a/docs/getting-started/cql.rst b/docs/getting-started/cql.rst
--- a/docs/getting-started/cql.rst
+++ b/docs/getting-started/cql.rst
@@ -0,0 +1,28 @@
+Cassandra Query Language (CQL)
+==============================
+
+.. toctree::
+ :hidden:
+
+ CQLSh the CQL shell <cqlsh>
+ Data Definition </getting-started/ddl>
+ Data Manipulation </getting-started/dml>
+ Expiring Data with Time to Live </getting-started/time-to-live>
+ Security </operating-scylla/security/index>
+ Data Types </getting-started/types>
+ Appendices </getting-started/appendices>
+ Definitions </getting-started/definitions>
+ Materialized Views </getting-started/mv>
+ Functions </getting-started/functions>
+ JSON </getting-started/json>
+ Secondary Indexes </getting-started/secondary-indexes>
+ Compaction </getting-started/compaction>
+ Consistency Levels </getting-started/consistency>
+ Reserved Keywords </getting-started/reserved-keywords>
+ Non-reserved Keywords </getting-started/non-reserved-keywords>
+
+.. include:: /rst_include/cql-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
+.. Operators </getting-started/operators>
diff --git a/docs/getting-started/cqlsh.rst b/docs/getting-started/cqlsh.rst
--- a/docs/getting-started/cqlsh.rst
+++ b/docs/getting-started/cqlsh.rst
@@ -0,0 +1,537 @@
+
+.. highlight:: none
+
+.. _cqlsh:
+
+CQLSh: the CQL shell
+--------------------
+
+cqlsh is a command line shell for interacting with Cassandra through CQL (the Cassandra Query Language). It is shipped
+with every Cassandra package and can be found in the bin/ directory alongside the Cassandra executable. cqlsh utilizes
+the Python native protocol driver and connects to the single node specified on the command line.
+
+
+Compatibility
+^^^^^^^^^^^^^
+
+cqlsh is compatible with Python 2.7.
+
+In general, a given version of cqlsh is only guaranteed to work with the version of Cassandra that it was released with.
+In some cases, cqlsh may work with older or newer versions of Cassandra, but this is not officially supported.
+
+
+Optional Dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+cqlsh ships with all essential dependencies. However, there are some optional dependencies that can be installed to
+improve the capabilities of cqlsh.
+
+pytz
+~~~~
+
+By default, cqlsh displays all timestamps with a UTC timezone. To support display of timestamps with another timezone,
+the `pytz <http://pytz.sourceforge.net/>`__ library must be installed. See the ``timezone`` option in cqlshrc_ for
+specifying a timezone to use.
+
+cython
+~~~~~~
+
+The performance of cqlsh's ``COPY`` operations can be improved by installing `cython <http://cython.org/>`__. This will
+compile the python modules that are central to the performance of ``COPY``.
+
+cqlshrc
+^^^^^^^
+
+
+The ``cqlshrc`` file holds configuration options for cqlsh. By default, this is in the user's home directory:
+
+``~/.cassandra/cqlsh``, but a custom location can be specified with the ``--cqlshrc`` option.
+
+Example config values and documentation can be found in the ``conf/cqlshrc.sample`` file of a tarball installation. You
+can also view the latest version of `cqlshrc online <https://github.com/scylladb/scylla-tools-java/blob/master/conf/cqlshrc.sample>`_.
+
+
+Command Line Options
+^^^^^^^^^^^^^^^^^^^^
+
+Usage:
+
+``cqlsh [options] [host [port]]``
+
+Options:
+
+``-C`` ``--color``
+ Force color output
+
+``--no-color``
+ Disable color output
+
+``--browser``
+ Specify the browser to use for displaying cqlsh help. This can be one of the `supported browser names
+ <https://docs.python.org/2/library/webbrowser.html>`__ (e.g. ``firefox``) or a browser path followed by ``%s`` (e.g.
+ ``/usr/bin/google-chrome-stable %s``).
+
+``--ssl``
+ Use SSL when connecting to Cassandra
+
+``-u`` ``--user``
+ Username to authenticate against Cassandra with
+
+``-p`` ``--password``
+ The password to authenticate against Cassandra with should
+ be used in conjunction with ``--user``
+
+``-k`` ``--keyspace``
+ Keyspace to authenticate to should be used in conjunction
+ with ``--user``
+
+``-f`` ``--file``
+ Execute commands from the given file, then exit
+
+``--debug``
+ Print additional debugging information
+
+``--encoding``
+ Specify a non-default encoding for output (defaults to UTF-8)
+
+``--cqlshrc``
+ Specify a non-default location for the ``cqlshrc`` file
+
+``-e`` ``--execute``
+ Execute the given statement, then exit
+
+``--connect-timeout``
+ Specify the connection timeout in seconds (defaults to 2s)
+
+``--request-timeout``
+ Specify the request timeout in seconds (defaults to 10s)
+
+``-t`` ``--tty``
+ Force tty mode (command prompt)
+
+
+Special Commands
+^^^^^^^^^^^^^^^^
+
+In addition to supporting regular CQL statements, cqlsh also supports a number of special commands that are not part of
+CQL. These are detailed below.
+
+.. _cqlsh-consistency:
+
+CONSISTENCY
+~~~~~~~~~~~
+
+`Usage`: ``CONSISTENCY <consistency level>``
+
+Sets the consistency level for operations to follow. Valid arguments include:
+
+.. code-block:: cql
+
+ - ANY
+ - ONE
+ - TWO
+ - THREE
+ - QUORUM
+ - ALL
+ - LOCAL_QUORUM
+ - LOCAL_ONE
+ - SERIAL
+ - LOCAL_SERIAL
+
+.. _cqlsh-serial-consistency:
+
+SERIAL CONSISTENCY
+~~~~~~~~~~~~~~~~~~
+
+`Usage`: ``SERIAL CONSISTENCY <consistency level>``
+
+Sets the serial consistency level for operations to follow. Valid arguments include:
+
+- ``SERIAL``
+- ``LOCAL_SERIAL``
+
+The serial consistency level is only used by conditional updates (``INSERT``, ``UPDATE``, and ``DELETE`` with an ``IF``
+condition). For those, the serial consistency level defines the consistency level of the serial phase (or “paxos” phase)
+while the normal consistency level defines the consistency for the “learn” phase, i.e. what type of reads will be
+guaranteed to see the update right away. For example, if a conditional write has a consistency level of ``QUORUM`` (and
+is successful), then a ``QUORUM`` read is guaranteed to see that write. However, if the regular consistency level of that
+write is ``ANY``, then only a read with a consistency level of ``SERIAL`` is guaranteed to see it (even a read with
+consistency ``ALL`` is not guaranteed to be enough).
+
+.. _cqlsh-show-version:
+
+SHOW VERSION
+~~~~~~~~~~~~
+This command is useful if you want to check which Cassandra version is compatible with your Scylla version.
+Note that the two standards are not 100% identical and this command is simply a comparison tool.
+
+If you want to display your current Scylla Version, refer to :ref:`Check your current version of Scylla <check-your-current-version-of-scylla>`.
+
+The display shows:
+
+* The cqlsh tool version that you're using
+* The Apache Cassandra version that your version of Scylla is most compatible with
+* The CQL protocol standard that your version of Scylla is most compatible with
+* The native protocol standard that your version of Scylla is most compatible with
+
+Example:
+
+.. code-block:: none
+
+ cqlsh> SHOW VERSION
+
+Returns:
+
+.. code-block:: none
+
+ [cqlsh 5.0.1 | Cassandra 3.0.8 | CQL spec 3.3.1 | Native protocol v4]
+
+.. _cqlsh-show-host:
+
+SHOW HOST
+~~~~~~~~~
+
+Prints the IP address and port of the Cassandra node that cqlsh is connected to in addition to the cluster name.
+
+Example:
+
+.. code-block:: none
+
+ cqlsh> SHOW HOST
+
+Returns:
+
+.. code-block:: none
+
+ Connected to Prod_Cluster at 192.0.0.1:9042.
+
+.. _cqlsh-show-session:
+
+SHOW SESSION
+~~~~~~~~~~~~
+
+Pretty prints a specific tracing session.
+
+`Usage`: ``SHOW SESSION <session id>``
+
+Example usage:
+
+
+.. code-block:: none
+
+ cqlsh> SHOW SESSION 95ac6470-327e-11e6-beca-dfb660d92ad8
+
+Returns:
+
+.. code-block:: none
+
+ Tracing session: 95ac6470-327e-11e6-beca-dfb660d92ad8
+
+ activity | timestamp | source | source_elapsed | client
+ -----------------------------------------------------------+----------------------------+-----------+----------------+-----------
+ Execute CQL3 query | 2016-06-14 17:23:13.979000 | 127.0.0.1 | 0 | 127.0.0.1
+ Parsing SELECT * FROM system.local; [SharedPool-Worker-1] | 2016-06-14 17:23:13.982000 | 127.0.0.1 | 3843 | 127.0.0.1
+ ...
+
+.. _cqlsh-source:
+
+SOURCE
+~~~~~~
+
+Reads the contents of a file and executes each line as a CQL statement or special cqlsh command.
+
+`Usage`: ``SOURCE <string filename>``
+
+Example usage::
+
+ cqlsh> SOURCE '/home/thobbs/commands.cql'
+
+.. _cqlsh-capture:
+
+CAPTURE
+~~~~~~~
+
+Begins capturing command output and appending it to a specified file. Output will not be shown at the console while it
+is captured.
+
+`Usage`::
+
+ CAPTURE '<file>';
+ CAPTURE OFF;
+ CAPTURE;
+
+That is, the path to the file to be appended to must be given inside a string literal. The path is interpreted relative
+to the current working directory. The tilde shorthand notation (``'~/mydir'``) is supported for referring to ``$HOME``.
+
+Only query result output is captured. Errors and output from cqlsh-only commands will still be shown in the cqlsh
+session.
+
+To stop capturing output and show it in the cqlsh session again, use ``CAPTURE OFF``.
+
+To inspect the current capture configuration, use ``CAPTURE`` with no arguments.
+
+.. _cqlsh-help:
+
+HELP
+~~~~
+
+Gives information about cqlsh commands. To see available topics, enter ``HELP`` without any arguments. To see help on a
+topic, use ``HELP <topic>``. Also, see the ``--browser`` argument for controlling what browser is used to display help.
+
+.. _cqlsh-tracing:
+
+TRACING
+~~~~~~~
+
+Enables or disables tracing for queries. When tracing is enabled, once a query completes, a trace of the events during
+the query will be printed.
+
+`Usage`::
+
+ TRACING ON
+ TRACING OFF
+
+.. _cqlsh-paging:
+
+PAGING
+~~~~~~
+
+Enables paging, disables paging, or sets the page size for read queries. When paging is enabled, only one page of data
+will be fetched at a time, and a prompt will appear to fetch the next page. Generally, it's a good idea to leave paging
+enabled in an interactive session to avoid fetching and printing large amounts of data at once.
+
+`Usage`::
+
+ PAGING ON
+ PAGING OFF
+ PAGING <page size in rows>
+
+.. _cqlsh-expand:
+
+EXPAND
+~~~~~~
+
+Enables or disables vertical printing of rows. Enabling ``EXPAND`` is useful when many columns are fetched, or the
+contents of a single column are large.
+
+`Usage`::
+
+ EXPAND ON
+ EXPAND OFF
+
+.. _cqlsh-login:
+
+LOGIN
+~~~~~
+
+Authenticate as a specified Cassandra user for the current session.
+
+`Usage`::
+
+ LOGIN <username> [<password>]
+
+.. _cqlsh-exit:
+
+EXIT
+~~~~
+
+Ends the current session and terminates the cqlsh process.
+
+`Usage`::
+
+ EXIT
+ QUIT
+
+.. _cqlsh-clear:
+
+CLEAR
+~~~~~~
+
+Clears the console.
+
+`Usage`::
+
+ CLEAR
+ CLS
+
+.. _cqlsh-describe:
+
+DESCRIBE
+~~~~~~~~
+
+Prints a description (typically a series of DDL statements) of a schema element or the cluster. This is useful for
+dumping all or portions of the schema.
+
+.. code-block:: cql
+
+ DESCRIBE CLUSTER
+ DESCRIBE SCHEMA
+ DESCRIBE KEYSPACES
+ DESCRIBE KEYSPACE <keyspace name>
+ DESCRIBE TABLES
+ DESCRIBE TABLE <table name>
+ DESCRIBE MATERIALIZED VIEW <view name>
+ DESCRIBE TYPES
+ DESCRIBE TYPE <type name>
+ DESCRIBE FUNCTIONS
+ DESCRIBE FUNCTION <function name>
+ DESCRIBE AGGREGATES
+ DESCRIBE AGGREGATE <aggregate function name>
+
+In any of the commands, ``DESC`` may be used in place of ``DESCRIBE``.
+
+The ``DESCRIBE CLUSTER`` command prints the cluster name and partitioner::
+
+
+ cqlsh> DESCRIBE CLUSTER
+
+ Cluster: Test Cluster
+ Partitioner: Murmur3Partitioner
+
+The ``DESCRIBE SCHEMA`` command prints the DDL statements needed to recreate the entire schema. This is especially
+useful for dumping the schema in order to clone a cluster or restore from a backup.
+
+.. _cqlsh-copy-to:
+
+COPY TO
+~~~~~~~
+
+Copies data from a table to a CSV file.
+
+.. code-block:: cql
+
+ COPY <table name> [(<column>, ...)] TO <file name> WITH <copy option> [AND <copy option> ...]
+
+If no columns are specified, all columns from the table will be copied to the CSV file. A subset of columns to copy may
+be specified by adding a comma-separated list of column names surrounded by parenthesis after the table name.
+
+
+The ``<file name>`` should be a string literal (with single quotes) representing a path to the destination file. The
+file name can also contain the special value ``STDOUT`` (without single quotes) print the CSV to STDOUT.
+
+See :ref:`shared-copy-options` for options that apply to both ``COPY TO`` and ``COPY FROM``.
+
+Options for COPY TO
+```````````````````
+
+``MAXREQUESTS``
+ The maximum number token ranges to fetch simultaneously. Defaults to 6.
+
+``PAGESIZE``
+ The number of rows to fetch in a single page. Defaults to 1000.
+
+``PAGETIMEOUT``
+ By default, the page timeout is 10 seconds per 1000 entries
+ in the page size or 10 seconds if pagesize is smaller.
+
+``BEGINTOKEN``, ``ENDTOKEN``
+ Token range to export. Defaults to exporting the full ring.
+
+``MAXOUTPUTSIZE``
+ The maximum size of the output file measured in number of lines;
+ beyond this maximum the output file will be split into segments.
+ -1 means unlimited, and is the default.
+
+``ENCODING``
+ The encoding used for characters. Defaults to ``utf8``.
+
+.. _cqlsh-copy-from:
+
+COPY FROM
+~~~~~~~~~
+Copies data from a CSV file to table.
+
+.. code-block:: cql
+
+ COPY <table name> [(<column>, ...)] FROM <file name> WITH <copy option> [AND <copy option> ...]
+
+If no columns are specified, all columns from the CSV file will be copied to the table. A subset
+of columns to copy may be specified by adding a comma-separated list of column names surrounded
+by parenthesis after the table name.
+
+The ``<file name>`` should be a string literal (with single quotes) representing a path to the
+source file. The file name can also contain the special value``STDIN`` (without single quotes)
+to read the CSV data from STDIN.
+
+See :ref:`shared-copy-options` for options that apply to both ``COPY TO`` and ``COPY FROM``.
+
+Options for COPY FROM
+`````````````````````
+
+``INGESTRATE``
+ The maximum number of rows to process per second. Defaults to 100000.
+
+``MAXROWS``
+ The maximum number of rows to import. -1 means unlimited, and is the default.
+
+``SKIPROWS``
+ A number of initial rows to skip. Defaults to 0.
+
+``SKIPCOLS``
+ A comma-separated list of column names to ignore. By default, no columns are skipped.
+
+``MAXPARSEERRORS``
+ The maximum global number of parsing errors to ignore. -1 means unlimited, and is the default.
+
+``MAXINSERTERRORS``
+ The maximum global number of insert errors to ignore. -1 means unlimited. The default is 1000.
+
+``ERRFILE`` =
+ A file to store all rows that could not be imported. By default, this is ``import_<ks>_<table>.err`` where ``<ks>`` is
+ your keyspace and ``<table>`` is your table name.
+
+``MAXBATCHSIZE``
+ The max number of rows inserted in a single batch. Defaults to 20.
+
+``MINBATCHSIZE``
+ The min number of rows inserted in a single batch. Defaults to 2.
+
+``CHUNKSIZE``
+ The number of rows that are passed to child worker processes from the main process at a time. Defaults to 1000.
+
+.. _shared-copy-options:
+
+Shared COPY Options
+```````````````````
+
+Options that are common to both ``COPY TO`` and ``COPY FROM``.
+
+``NULLVAL``
+ The string placeholder for null values. Defaults to ``null``.
+
+``HEADER``
+ For ``COPY TO``, controls whether the first line in the CSV output file will contain the column names. For COPY FROM,
+ specifies whether the first line in the CSV input file contains column names. Defaults to ``false``.
+
+``DECIMALSEP``
+ The character that is used as the decimal point separator. Defaults to ``.``.
+
+``THOUSANDSSEP``
+ The character that is used to separate thousands. Defaults to the empty string.
+
+``BOOLSTYlE``
+ The string literal format for boolean values. By default this is ``True, False``.
+
+``NUMPROCESSES``
+ The number of child worker processes to create for ``COPY`` tasks. Defaults to a max of 4 for ``COPY FROM`` and 16
+ for ``COPY TO``. However, at most (num_cores - 1), processes will be created.
+
+``MAXATTEMPTS``
+ The maximum number of failed attempts to fetch a range of data (when using ``COPY TO``) or insert a chunk of data
+ (when using ``COPY FROM``) before giving up. Defaults to 5.
+
+``REPORTFREQUENCY``
+ How often status updates are refreshed in seconds. By default, this is 0.25 seconds.
+
+``RATEFILE``
+ An optional file to export rate statistics to. By default, this is disabled and statistics are not exported to a file.
+
+See also:
+
+CQLSH `lesson <https://university.scylladb.com/courses/data-modeling/lessons/basic-data-modeling-2/topic/cql-cqlsh-and-basic-cql-syntax/>`_ on Scylla University
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+:doc:`Back </getting-started/index/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/ddl.rst b/docs/getting-started/ddl.rst
--- a/docs/getting-started/ddl.rst
+++ b/docs/getting-started/ddl.rst
@@ -0,0 +1,989 @@
+.. highlight:: cql
+
+Data Definition
+===============
+
+
+.. include:: /rst_include/cql-version-index.rst
+
+CQL stores data in *tables*, whose schema defines the layout of said data in the table, and those tables are grouped in
+*keyspaces*. A keyspace defines a number of options that apply to all the tables it contains, most prominently of
+which is the replication strategy used by the keyspace. An application can have only one keyspace. However, it is also possible to
+have multiple keyspaces in case your application has different replication requirements.
+
+This section describes the statements used to create, modify, and remove keyspaces and tables.
+
+:ref:`CREATE KEYSPACE <create-keyspace-statement>`
+
+.. _create-keyspace:
+
+:ref:`USE <use-statement>`
+
+.. _use:
+
+:ref:`ALTER KEYSPACE <alter-keyspace-statement>`
+
+.. _ALTER KEYSPACE:
+
+:ref:`DROP KEYSPACE <drop-keyspace-statement>`
+
+.. _DROP KEYSPACE:
+
+:ref:`CREATE TABLE <create-table-statement>`
+
+.. _CREATE TABLE:
+
+:ref:`ALTER TABLE <alter-table-statement>`
+
+.. _ALTER TABLE:
+
+:ref:`DROP TABLE <drop-table-statement>`
+
+.. _DROP TABLE:
+
+:ref:`TRUNCATE <truncate-statement>`
+
+.. _TRUNCATE:
+
+.. _data-definition:
+
+Common Definitions
+^^^^^^^^^^^^^^^^^^
+
+Keyspace and table names are defined by the following grammar:
+
+.. code-block:: cql
+
+ keyspace_name: `name`
+ table_name: [ `keyspace_name` '.' ] `name`
+ name: `unquoted_name` | `quoted_name`
+ unquoted_name: re('[a-zA-Z_0-9]{1, 48}')
+ quoted_name: '"' `unquoted_name` '"'
+
+Both keyspace and table names consist of only alphanumeric characters, cannot be empty, and are limited in
+size to 48 characters (that limit exists mostly to avoid filenames, which may include the keyspace and table name, to go
+over the limits of certain file systems). By default, keyspace and table names are case insensitive (``myTable`` is
+equivalent to ``mytable``), but case sensitivity can be forced by using double-quotes (``"myTable"`` is different from
+``mytable``).
+
+Further, a table is always part of a keyspace, and a table name can be provided fully-qualified by the keyspace it is
+part of. If it is not fully-qualified, the table is assumed to be in the *current* keyspace (see :ref:`USE statement
+<use-statement>`).
+
+Further, valid column names are simply defined as:
+
+.. code-block:: cql
+
+ column_name: `identifier`
+
+We also define the notion of statement options for use in the following section:
+
+.. code-block:: cql
+
+ options: `option` ( AND `option` )*
+ option: `identifier` '=' ( `identifier` | `constant` | `map_literal` )
+
+.. _create-keyspace-statement:
+
+In all cases, for creating keyspaces and tables, if you are using :doc:`Reserved Keywords </getting-started/reserved-keywords>`, enclose them in single or double-quotes.
+
+CREATE KEYSPACE
+^^^^^^^^^^^^^^^
+
+A keyspace is created using a ``CREATE KEYSPACE`` statement:
+
+.. code-block:: cql
+
+ create_keyspace_statement: CREATE KEYSPACE [ IF NOT EXISTS ] `keyspace_name` WITH `options`
+
+For example:
+
+.. code-block:: cql
+
+ CREATE KEYSPACE Excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1' : 1, 'DC2' : 3}
+ AND durable_writes = true;
+
+
+.. code-block:: cql
+
+ CREATE KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 3};
+
+
+The supported ``options`` are:
+
+=================== ========== =========== ========= ===================================================================
+name kind mandatory default description
+=================== ========== =========== ========= ===================================================================
+``replication`` *map* yes The replication strategy and options to use for the keyspace (see
+ details below).
+``durable_writes`` *simple* no true Whether to use the commit log for updates on this keyspace
+ (disable this option at your own risk!).
+=================== ========== =========== ========= ===================================================================
+
+The ``replication`` property is mandatory and must at least contains the ``'class'`` sub-option, which defines the
+replication strategy class to use. The rest of the sub-options depend on what replication
+strategy is used. By default, Scylla supports the following ``'class'``:
+
+.. _replication-strategy:
+
+SimpleStrategy
+~~~~~~~~~~~~~~~
+
+A simple strategy that defines a replication factor for data to be spread
+across the entire cluster. This is generally not a wise choice for production
+because it does not respect datacenter layouts and can lead to wildly varying
+query latency. For a production ready strategy, see *NetworkTopologyStrategy* . *SimpleStrategy* supports a single mandatory argument:
+
+========================= ====== ======= =============================================
+sub-option type since description
+========================= ====== ======= =============================================
+``'replication_factor'`` int all The number of replicas to store per range
+========================= ====== ======= =============================================
+
+.. note:: Using NetworkTopologyStrategy is recommended. Using SimpleStrategy will make it harder to add Data Center in the future.
+
+NetworkTopologyStrategy
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A production ready replication strategy that allows to set the replication
+factor independently for each data-center. The rest of the sub-options are
+key-value pairs where a key is a data-center name and its value is the
+associated replication factor. Options:
+
+===================================== ====== =============================================
+sub-option type description
+===================================== ====== =============================================
+``'<datacenter>'`` int The number of replicas to store per range in
+ the provided datacenter.
+``'replication_factor'`` int The number of replicas to use as a default
+ per datacenter if not specifically provided.
+ Note that this always defers to existing
+ definitions or explicit datacenter settings.
+ For example, to have three replicas per
+ datacenter, supply this with a value of 3.
+===================================== ====== =============================================
+
+Note that when ``ALTER`` ing keyspaces and supplying ``replication_factor``,
+auto-expansion will only *add* new datacenters for safety, it will not alter
+existing datacenters or remove any even if they are no longer in the cluster.
+If you want to remove datacenters while still supplying ``replication_factor``,
+explicitly zero out the datacenter you want to have zero replicas.
+
+An example of auto-expanding datacenters with two datacenters: ``DC1`` and ``DC2``::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3}
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3', 'DC2': '3'} AND durable_writes = true;
+
+
+An example of auto-expanding and overriding a datacenter::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3, 'DC2': 2}
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3', 'DC2': '2'} AND durable_writes = true;
+
+An example that excludes a datacenter while using ``replication_factor``::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3, 'DC2': 0} ;
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3'} AND durable_writes = true;
+
+.. _use-statement:
+
+USE
+^^^
+
+The ``USE`` statement allows you to change the *current* keyspace (for the *connection* on which it is executed). Some objects in CQL are bound to a keyspace (tables, user-defined types, functions, ...), and the current keyspace is the
+default keyspace used when those objects are referred without a fully-qualified name (that is, without being prefixed a
+keyspace name). A ``USE`` statement simply takes the specified keyspace and uses the name as an argument for all future actions until this name is changed.
+
+.. code-block:: cql
+
+ use_statement: USE `keyspace_name`
+
+.. _alter-keyspace-statement:
+
+ALTER KEYSPACE
+^^^^^^^^^^^^^^
+
+An ``ALTER KEYSPACE`` statement lets you modify the options of a keyspace:
+
+.. code-block:: cql
+
+ alter_keyspace_statement: ALTER KEYSPACE `keyspace_name` WITH `options`
+
+For instance::
+
+ ALTER KEYSPACE Excelsior
+ WITH replication = { 'class' : 'NetworkTopologyStrategy', 'dc1' : 3, 'dc2' : 0};
+
+
+ ALTER KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4};
+
+
+
+The supported options are the same as :ref:`creating a keyspace <create-keyspace-statement>`.
+
+.. _drop-keyspace-statement:
+
+DROP KEYSPACE
+^^^^^^^^^^^^^
+
+Dropping a keyspace can be done using the ``DROP KEYSPACE`` statement:
+
+.. code-block:: cql
+
+ drop_keyspace_statement: DROP KEYSPACE [ IF EXISTS ] `keyspace_name`
+
+For instance::
+
+ DROP KEYSPACE Excelsior;
+
+Dropping a keyspace results in the immediate removal of that keyspace, including all the tables, UTD and
+functions in it, and all the data contained in those tables.
+
+.. include:: /getting-started/_common/note-reclaim-space.rst
+
+If the keyspace does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case the
+operation is a no-op.
+
+.. _create-table-statement:
+
+CREATE TABLE
+^^^^^^^^^^^^
+
+Creating a new table uses the ``CREATE TABLE`` statement:
+
+.. code-block:: cql
+
+ create_table_statement: CREATE TABLE [ IF NOT EXISTS ] `table_name`
+ : '('
+ : `column_definition`
+ : ( ',' `column_definition` )*
+ : [ ',' PRIMARY KEY '(' `primary_key` ')' ]
+ : ')' [ WITH `table_options` ]
+
+ column_definition: `column_name` `cql_type` [ STATIC ] [ PRIMARY KEY]
+
+ primary_key: `partition_key` [ ',' `clustering_columns` ]
+
+ partition_key: `column_name`
+ : | '(' `column_name` ( ',' `column_name` )* ')'
+
+ clustering_columns: `column_name` ( ',' `column_name` )*
+
+ table_options: COMPACT STORAGE [ AND `table_options` ]
+ : | CLUSTERING ORDER BY '(' `clustering_order` ')' [ AND `table_options` ]
+ : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'
+ : | caching '=' ' {'caching_options'}'
+ : | `options`
+
+ clustering_order: `column_name` (ASC | DESC) ( ',' `column_name` (ASC | DESC) )*
+
+For instance::
+
+ CREATE TABLE monkeySpecies (
+ species text PRIMARY KEY,
+ common_name text,
+ population varint,
+ average_size int
+ ) WITH comment='Important biological records'
+ AND read_repair_chance = 1.0;
+
+ CREATE TABLE timeline (
+ userid uuid,
+ posted_month int,
+ posted_time uuid,
+ body text,
+ posted_by text,
+ PRIMARY KEY (userid, posted_month, posted_time)
+ ) WITH compaction = { 'class' : 'LeveledCompactionStrategy' };
+
+ CREATE TABLE loads (
+ machine inet,
+ cpu int,
+ mtime timeuuid,
+ load float,
+ PRIMARY KEY ((machine, cpu), mtime)
+ ) WITH CLUSTERING ORDER BY (mtime DESC);
+
+ CREATE TABLE users_picture (
+ userid uuid,
+ pictureid uuid,
+ body text,
+ posted_by text,
+ PRIMARY KEY (userid, pictureid, posted_by)
+ ) WITH compression = {'sstable_compression': 'LZ4Compressor'};
+
+
+ CREATE TABLE data_atrest (
+ pk text PRIMARY KEY,
+ c0 int
+ ) WITH scylla_encryption_options = {
+ 'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
+ 'secret_key_strength' : 128,
+ 'key_provider': 'LocalFileSystemKeyProviderFactory',
+ 'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};
+
+ CREATE TABLE caching (
+ k int PRIMARY KEY,
+ v1 int,
+ v2 int,
+ ) WITH caching = {'enabled': 'true'};
+
+
+A CQL table has a name and is composed of a set of *rows*. Creating a table amounts to defining which :ref:`columns
+<column-definition>` the rows will be composed, which of those columns compose the :ref:`primary key <primary-key>`, as
+well as optional :ref:`options <create-table-options>` for the table.
+
+Attempting to create an already existing table will return an error unless the ``IF NOT EXISTS`` directive is used. If
+it is used, the statement will be a no-op if the table already exists.
+
+
+.. _column-definition:
+
+Column definitions
+~~~~~~~~~~~~~~~~~~
+
+Every row in a CQL table has a set of predefined columns defined at the time of the table creation (or added later
+using an :ref:`alter statement<alter-table-statement>`).
+
+A :token:`column_definition` is primarily comprised of the name of the column defined and its :ref:`type <data-types>`,
+which restricts which values are accepted for that column. Additionally, a column definition can have the following
+modifiers:
+
+``STATIC``
+ declares the column as being a :ref:`static column <static-columns>`.
+
+``PRIMARY KEY``
+ declares the column as being the sole component of the :ref:`primary key <primary-key>` of the table.
+
+.. _static-columns:
+
+Static columns
+``````````````
+Some columns can be declared as ``STATIC`` in a table definition. A column that is static will be “shared” by all the
+rows belonging to the same partition (having the same :ref:`partition key <partition-key>`). For instance::
+
+ CREATE TABLE t (
+ pk int,
+ t int,
+ v text,
+ s text static,
+ PRIMARY KEY (pk, t)
+ );
+
+ INSERT INTO t (pk, t, v, s) VALUES (0, 0, 'val0', 'static0');
+ INSERT INTO t (pk, t, v, s) VALUES (0, 1, 'val1', 'static1');
+
+ SELECT * FROM t;
+ pk | t | v | s
+ ----+---+--------+-----------
+ 0 | 0 | 'val0' | 'static1'
+ 0 | 1 | 'val1' | 'static1'
+
+As can be seen, the ``s`` value is the same (``static1``) for both of the rows in the partition (the partition key in
+that example being ``pk``, both rows are in that same partition): the 2nd insertion has overridden the value for ``s``.
+
+Static columns have the following restrictions:
+
+- tables with the ``COMPACT STORAGE`` option (see below) cannot use them.
+- a table without clustering columns cannot have static columns (in a table without clustering columns, every partition
+ has only one row, and so every column is inherently static).
+- only non ``PRIMARY KEY`` columns can be static.
+
+.. _primary-key:
+
+The Primary key
+~~~~~~~~~~~~~~~
+
+Within a table, a row is uniquely identified by its ``PRIMARY KEY``, and hence all tables **must** define a PRIMARY KEY
+(and only one). A ``PRIMARY KEY`` definition is composed of one or more of the columns defined in the table.
+Syntactically, the primary key is defined by the keywords ``PRIMARY KEY``, followed by a comma-separated list of the column
+names composing it within parenthesis. However, if the primary key has only one column, one can alternatively follow that
+column definition by the ``PRIMARY KEY`` keywords. The order of the columns in the primary key definition matter.
+
+A CQL primary key is composed of 2 parts:
+
+- the :ref:`partition key <partition-key>` part. It is the first component of the primary key definition. It can be a
+ single column or, using additional parenthesis, can be multiple columns. A table always has at least a partition key,
+ the smallest possible table definition is::
+
+ CREATE TABLE t (k text PRIMARY KEY);
+
+- the :ref:`clustering columns <clustering-columns>`. Those are the columns after the first component of the primary key
+ definition, and the order of those columns define the *clustering order*.
+
+Some examples of primary key definition are:
+
+- ``PRIMARY KEY (a)``: ``a`` is the partition key, and there are no clustering columns.
+- ``PRIMARY KEY (a, b, c)``: ``a`` is the partition key, and ``b`` and ``c`` are the clustering columns.
+- ``PRIMARY KEY ((a, b), c)``: ``a`` and ``b`` compose the partition key (this is often called a *composite* partition
+ key), and ``c`` is the clustering column.
+
+
+.. note:: A *null* value is not allowed as any partition-key or clustering-key column. A Null value is *not* the same as an empty string.
+
+.. _partition-key:
+
+The partition key
+`````````````````
+
+Within a table, CQL defines the notion of a *partition*. A partition is simply the set of rows that share the same value
+for their partition key. Note that if the partition key is composed of multiple columns, then rows belong to the same
+partition only when they have the same values for all those partition key columns. So, for instance, given the following table
+definition and content::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ d int,
+ PRIMARY KEY ((a, b), c, d)
+ );
+
+ SELECT * FROM t;
+ a | b | c | d
+ ---+---+---+---
+ 0 | 0 | 0 | 0 // row 1
+ 0 | 0 | 1 | 1 // row 2
+ 0 | 1 | 2 | 2 // row 3
+ 0 | 1 | 3 | 3 // row 4
+ 1 | 1 | 4 | 4 // row 5
+
+``row 1`` and ``row 2`` are in the same partition, ``row 3`` and ``row 4`` are also in the same partition (but a
+different one) and ``row 5`` is in yet another partition.
+
+Note that a table always has a partition key and that if the table has no :ref:`clustering columns
+<clustering-columns>`, then every partition of that table is only comprised of a single row (since the primary key
+uniquely identifies rows and the primary key is equal to the partition key if there are no clustering columns).
+
+The most important property of partition is that all the rows belonging to the same partition are guarantee to be stored
+on the same set of replica nodes. In other words, the partition key of a table defines which of the rows will be
+localized together in the cluster, and it is thus important to choose your partition key wisely so that rows that need
+to be fetched together are in the same partition (so that querying those rows together require contacting a minimum of
+nodes).
+
+However, please note that there is a flip-side to this guarantee: as all rows sharing a partition key are guaranteed to
+be stored on the same set of replica nodes, a partition key that groups too much data can create a hotspot.
+
+Another useful property of a partition is that when writing data, all the updates belonging to a single partition are
+done *atomically* and in *isolation*, which is not the case across partitions.
+
+The proper choice of the partition key and clustering columns for a table is probably one of the most important aspects
+of data modeling in Scylla. It largely impacts which queries can be performed and how efficient they are.
+
+.. note:: An empty string is *not* allowed as a partition key value. In a compound partition key (multiple partition-key columns), any or all of them may be empty strings. Empty string is *not* a Null value.
+
+
+.. _clustering-columns:
+
+The clustering columns
+``````````````````````
+
+The clustering columns of a table define the clustering order for the partition of that table. For a given
+:ref:`partition <partition-key>`, all the rows are physically ordered inside Scylla by that clustering order. For
+instance, given::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ PRIMARY KEY (a, b, c)
+ );
+
+ SELECT * FROM t;
+ a | b | c
+ ---+---+---
+ 0 | 0 | 4 // row 1
+ 0 | 1 | 9 // row 2
+ 0 | 2 | 2 // row 3
+ 0 | 3 | 3 // row 4
+
+then the rows (which all belong to the same partition) are all stored internally in the order of the values of their
+``b`` column (the order they are displayed above). So, where the partition keys of the table let you group rows on the
+same replica set, the clustering columns control how those rows are stored on the replica. That sorting allows the
+retrieval of a range of rows within a partition (for instance, in the example above, ``SELECT * FROM t WHERE a = 0 AND b
+> 1 and b <= 3``) is very efficient.
+
+.. note:: An empty string is allowed as a clustering key value. Empty string is *not* a Null value.
+
+
+.. _create-table-options:
+
+Table options
+~~~~~~~~~~~~~
+
+A CQL table has a number of options that can be set at creation (and, for most of them, :ref:`altered
+<alter-table-statement>` later). These options are specified after the ``WITH`` keyword.
+
+Amongst those options, two important ones cannot be changed after creation and influence which queries can be done
+against the table: the ``COMPACT STORAGE`` option and the ``CLUSTERING ORDER`` option. Those, as well as the other
+options of a table are described in the following sections.
+
+.. _compact-tables:
+
+Compact tables
+``````````````
+
+..
+ .. caution:: Since Apache Cassandra 3.0, compact tables have the exact same layout internally than non compact ones (for the
+ same schema obviously), and declaring a table compact **only** creates artificial limitations on the table definition
+ and usage. It only exists for historical reason and is preserved for backward compatibility And as ``COMPACT
+ STORAGE`` cannot, as of Apache Cassandra |version|, be removed, it is strongly discouraged to create new table with the
+ ``COMPACT STORAGE`` option.
+
+A *compact* table is one defined with the ``COMPACT STORAGE`` option. This option is only maintained for backward
+compatibility for definitions created before CQL version 3 and shouldn't be used for new tables. Declaring a
+table with this option creates limitations for the table, which are largely arbitrary (and exists for historical
+reasons). Amongst these limitations:
+
+- a compact table cannot use collections nor static columns.
+- if a compact table has at least one clustering column, then it must have *exactly* one column outside of the primary
+ key ones. This implies that you cannot add or remove columns in particular after creation.
+- a compact table is limited as to the indexes it can create, and no materialized view can be created on it.
+
+.. _clustering-order:
+
+Reversing the clustering order
+``````````````````````````````
+
+The clustering order of a table is defined by the :ref:`clustering columns <clustering-columns>` of that table. By
+default, that ordering is based on the natural order of the clustering order, but the ``CLUSTERING ORDER`` lets you
+change that clustering order to use the *reverse* natural order for some (potentially all) of the columns.
+
+The ``CLUSTERING ORDER`` option takes the comma-separated list of the clustering column, each with an ``ASC`` (for
+*ascendant*, e.g. the natural order) or ``DESC`` (for *descendant*, e.g. the reverse natural order). Note in particular
+that the default (if the ``CLUSTERING ORDER`` option is not used) is strictly equivalent to using the option with all
+clustering columns using the ``ASC`` modifier.
+
+Note that this option is basically a hint for the storage engine to change the order in which it stores the row, but it
+has three visible consequences:
+
+- it limits which ``ORDER BY`` clause is allowed for :ref:`selects <select-statement>` on that table. You can only
+ order results by the clustering order or the reverse clustering order. Meaning that if a table has two clustering columns
+ ``a`` and ``b``, and you define ``WITH CLUSTERING ORDER (a DESC, b ASC)``, then in queries, you will be allowed to use
+ ``ORDER BY (a DESC, b ASC)`` and (reverse clustering order) ``ORDER BY (a ASC, b DESC)`` but **not** ``ORDER BY (a
+ ASC, b ASC)`` (nor ``ORDER BY (a DESC, b DESC)``).
+- it also changes the default order of results when queried (if no ``ORDER BY`` is provided). Results are always returned
+ in clustering order (within a partition).
+- it has a small performance impact on some queries as queries in reverse clustering order are slower than the one in
+ forward clustering order. In practice, this means that if you plan on querying mostly in the reverse natural order of
+ your columns (which is common with time series, for instance, where you often want data from the newest to the oldest),
+ it is an optimization to declare a descending clustering order.
+
+.. _create-table-general-options:
+
+Other table options
+```````````````````
+
+.. _todo: review (misses cdc if nothing else) and link to proper categories when appropriate (compaction, for instance)
+
+A table supports the following options:
+
+.. list-table::
+ :widths: 20 10 10 60
+ :header-rows: 1
+
+ * - Option
+ - Kind
+ - Default
+ - Description
+ * - ``comment``
+ - simple
+ - none
+ - A free-form, human-readable comment.
+ * - ``read_repair_chance``
+ - simple
+ - 0
+ - The probability that extra nodes are queried (e.g. more nodes than required by the consistency level) for the purpose of read repairs.
+ * - ``dclocal_read_repair_chance``
+ - simple
+ - 0
+ - The probability that extra nodes are queried (e.g. more nodes than required by the consistency level) belonging to the same data center as the read coordinator for the purpose of read repairs.
+ * - ``speculative_retry``
+ - simple
+ - 99PERCENTILE
+ - :ref:`Speculative retry options <speculative-retry-options>`
+ * - ``gc_grace_seconds``
+ - simple
+ - 864000
+ - Time to wait before garbage collecting tombstones (deletion markers). See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+ * - ``tombstone_gc``
+ - mode
+ - see below
+ - The mode of garbage collecting tombstones. See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+ * - ``bloom_filter_fp_chance``
+ - simple
+ - 0.01
+ - The target probability of false-positive of the sstable bloom filters. Sstable bloom filters will be sized to provide the provided probability (thus lowering this value impact the size of bloom filters in-memory and on-disk).
+ * - ``default_time_to_live``
+ - simple
+ - 0
+ - The default expiration time (“TTL”) in seconds for a table.
+ * - ``compaction``
+ - map
+ - see below
+ - :ref:`Compaction options <cql-compaction-options>`
+ * - ``compaction``
+ - map
+ - see below
+ - :ref:`Compression options <cql-compression-options>`
+ * - ``caching``
+ - map
+ - see below
+ - :ref:`Caching Options <cql-caching-options>`
+ * - ``cdc``
+ - map
+ - see below
+ - :ref:`CDC Options <cdc-options>`
+
+
+.. _speculative-retry-options:
+
+Speculative retry options
+#########################
+
+By default, Scylla read coordinators only query as many replicas as necessary to satisfy
+consistency levels: one for consistency level ``ONE``, a quorum for ``QUORUM``, and so on.
+``speculative_retry`` determines when coordinators may query additional replicas, which is useful
+when replicas are slow or unresponsive. The following are legal values (case-insensitive):
+
+========================= ================ =============================================================================
+ Format Example Description
+========================= ================ =============================================================================
+ ``XPERCENTILE`` 90.5PERCENTILE Coordinators record average per-table response times for all replicas.
+ If a replica takes longer than ``X`` percent of this table's average
+ response time, the coordinator queries an additional replica.
+ ``X`` must be between 0 and 100.
+ ``XP`` 90.5P Synonym for ``XPERCENTILE``
+ ``Yms`` 25ms If a replica takes more than ``Y`` milliseconds to respond,
+ the coordinator queries an additional replica.
+ ``ALWAYS`` Coordinators always query all replicas.
+ ``NONE`` Coordinators never query additional replicas.
+========================= ================ =============================================================================
+
+This setting does not affect reads with consistency level ``ALL`` because they already query all replicas.
+
+Note that frequently reading from additional replicas can hurt cluster performance.
+When in doubt, keep the default ``99PERCENTILE``.
+
+
+.. _cql-compaction-options:
+
+Compaction options
+##################
+
+The ``compaction`` options must at least define the ``'class'`` sub-option, which defines the compaction strategy class
+to use. The default supported class are ``'SizeTieredCompactionStrategy'``,
+``'LeveledCompactionStrategy'``, ``'IncrementalCompactionStrategy'``, and ``'DateTieredCompactionStrategy'``
+Custom strategy can be provided by specifying the full class name as a :ref:`string constant
+<constants>`.
+
+All default strategies support a number of common options, as well as options specific to
+the strategy chosen (see the section corresponding to your strategy for details: :ref:`STCS <stcs-options>`, :ref:`LCS <lcs-options>`, :ref:`ICS <ics-options>`, and :ref:`TWCS <twcs-options>`). DTCS is not recommended, and TWCS should be used instead.
+
+
+.. ``'Date Tiered Compaction Strategy is not recommended and has been replaced by Time Window Compaction Stragegy.'`` (:ref:`TWCS <TWCS>`) (the
+.. is also supported but is deprecated and ``'TimeWindowCompactionStrategy'`` should be
+.. preferred instead).
+
+
+
+.. _cql-compression-options:
+
+Compression options
+###################
+
+The ``compression`` options define if and how the sstables of the table are compressed. The following sub-options are
+available:
+
+========================= =============== =============================================================================
+ Option Default Description
+========================= =============== =============================================================================
+ ``sstable_compression`` LZ4Compressor The compression algorithm to use. Default compressors are
+ LZ4Compressor, SnappyCompressor, and DeflateCompressor.
+ A custom compressor can be provided by specifying the full class
+ name as a “string constant”:#constants.
+ ``chunk_length_in_kb`` 4KB On disk SSTables are compressed by block (to allow random reads). This
+ defines the size (in KB) of the block. Bigger values may improve the
+ compression rate, but increases the minimum size of data to be read from disk
+ for a read.
+========================= =============== =============================================================================
+
+.. ``crc_check_chance`` 1.0 When compression is enabled, each compressed block includes a checksum of
+.. that block for the purpose of detecting disk bitrot and avoiding the
+.. propagation of corruption to other replicas. This option defines the
+.. probability with which those checksums are checked during read. By default
+.. they are always checked. Set to 0 to disable checksum checking and to 0.5 for
+.. instance to check them every other read |
+
+For example, to enable compression:
+
+.. code-block:: console
+
+
+ CREATE TABLE id (id int PRIMARY KEY) WITH compression = {'sstable_compression': 'LZ4Compressor'};
+
+
+For example, to disable compression:
+
+.. code-block:: console
+
+ CREATE TABLE id (id int PRIMARY KEY) WITH compression = {};
+
+
+.. _cdc-options:
+
+CDC options
+###########
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The following options are to be used with Change Data Capture. Available as an experimental feature from Scylla Open Source 3.2.
+To use this feature, you must enable the :ref:`experimental tag <yaml_enabling_experimental_features>` in the scylla.yaml.
+
+
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| option | default | description |
++===========================+=================+========================================================================================================================+
+| ``enabled`` | ``false`` | When set to ``true``, another table --- the CDC log table --- is created and associated with the table you are |
+| | | creating/altering (for example, customer_data). All writes made to this table (customer_data) are reflected in |
+| | | the corresponding CDC log table. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| ``preimage`` | ``false`` | When set to ``true``, it saves the result of what a client performing a write would display if it has queried this |
+| | | table before making the write into the corresponding CDC log table. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| ``ttl`` | 86400 seconds | Time after which data stored in CDC will be removed and won’t be accessible to the client anymore. |
+| | 24 hours | |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+
+For example:
+
+.. code-block:: cql
+
+ CREATE TABLE customer_data (
+ cust_id uuid,
+ cust_first-name text,
+ cust_last-name text,
+ cust_phone text,
+ cust_get-sms text,
+ PRIMARY KEY (customer_id)
+ ) WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };
+
+.. _cql-caching-options:
+
+Caching options
+###############
+
+Caching optimizes cache memory usage of a table. The cached data is weighed by size and access frequency.
+
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| option | default | description |
++===========================+=================+========================================================================================================================+
+| ``enabled`` | ``TRUE`` | When set to TRUE enables caching on the specified table. Valid options are TRUE and FALSE. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+
+
+For example,
+
+.. code-block:: cql
+
+ CREATE TABLE caching (
+ k int PRIMARY KEY,
+ v1 int,
+ v2 int,
+ ) WITH caching = {'enabled': 'true'};
+
+Encryption options
+###################
+
+Encryption options are used when enabling or disabling encryption at rest, available in Scylla Enterprise from version 2019.1.1.
+
+.. note:: When the ``key_provider`` is ``LocalFileSystemKeyProviderFactory``, you must indicate where the key resides using the ``secret_key_file: <path>`` parameter. Refer to :doc:`Encryption at Rest </operating-scylla/security/encryption-at-rest>` for details.
+
+.. _ddl-tombstones-gc:
+.. _gc_grace_seconds:
+
+Tombstones GC options
+#######################
+
+ScyllaDB inherited the ``gc_grace_seconds`` option from Apache Cassandra. The option allows you to specify the wait time
+(in seconds) before data marked with a deletion :term:`tombstone` is removed via compaction.
+This option assumes that you run :term:`repair` during the specified time. Failing to run repair during the wait
+time may result in the resurrection of deleted data.
+
+The ``tombstone_gc`` option allows you to prevent data resurrection. With the ``repair`` mode configured, :term:`tombstone`
+are only removed after :term:`repair` is performed. Unlike ``gc_grace_seconds``, ``tombstone_gc`` has no time constraints - when
+the ``repair`` mode is on, tombstones garbage collection will wait until repair is run.
+
+The ``tombstone_gc`` option can be enabled using ``ALTER TABLE`` and ``CREATE TABLE``. For example:
+
+.. code-block:: cql
+
+ CREATE TABLE ks.cf (key blob PRIMARY KEY, val blob) WITH tombstone_gc = {'mode':'repair'};
+
+.. code-block:: cql
+
+ ALTER TABLE ks.cf WITH tombstone_gc = {'mode':'repair'} ;
+
+.. note::
+ The ``tombstone_gc`` option was added in ScyllaDB 5.0 as an experimental feature, and it is disabled by default.
+ You need to explicitly specify the ``repair`` mode table property to enable the feature.
+
+The following modes are available:
+
+.. list-table::
+ :widths: 20 80
+ :header-rows: 1
+
+ * - Mode
+ - Description
+ * - ``timeout``
+ - Tombstone GC is performed after the wait time specified with ``gc_grace_seconds``. Default in ScyllaDB 5.0.
+ * - ``repair``
+ - Tombstone GC is performed after repair is run.
+ * - ``disabled``
+ - Tombstone GC is never performed. This mode may be useful when loading data to the database, to avoid tombstone GC when part of the data is not yet available.
+ * - ``immediate``
+ - Tombstone GC is immediately performed. There is no wait time or repair requirement. This mode is useful for a table that uses the TWCS compaction strategy with no user deletes. After data is expired after TTL, ScyllaDB can perform compaction to drop the expired data immediately.
+
+Other considerations:
+#####################
+
+- Adding new columns (see ``ALTER TABLE`` below) is a constant time operation. There is thus no need to try to
+ anticipate future usage when creating a table.
+
+.. _alter-table-statement:
+
+ALTER TABLE
+^^^^^^^^^^^
+
+Altering an existing table uses the ``ALTER TABLE`` statement:
+
+.. code-block:: cql
+
+ alter_table_statement: ALTER TABLE `table_name` `alter_table_instruction`
+ alter_table_instruction: ADD `column_name` `cql_type` ( ',' `column_name` `cql_type` )*
+ : | DROP `column_name`
+ : | DROP '(' `column_name` ( ',' `column_name` )* ')'
+ : | ALTER `column_name` TYPE `cql_type`
+ : | WITH `options`
+ : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'
+
+For instance:
+
+.. code-block:: cql
+
+ ALTER TABLE addamsFamily ADD gravesite varchar;
+
+ ALTER TABLE addamsFamily
+ WITH comment = 'A most excellent and useful table'
+ AND read_repair_chance = 0.2;
+
+
+ ALTER TABLE data_atrest (
+ pk text PRIMARY KEY,
+ c0 int
+ ) WITH scylla_encryption_options = {
+ 'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
+ 'secret_key_strength' : 128,
+ 'key_provider': 'LocalFileSystemKeyProviderFactory',
+ 'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};
+
+ ALTER TABLE customer_data
+ WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };
+
+The ``ALTER TABLE`` statement can:
+
+- Add new column(s) to the table (through the ``ADD`` instruction). Note that the primary key of a table cannot be
+ changed, and thus newly added column will, by extension, never be part of the primary key. Also, note that :ref:`compact
+ tables <compact-tables>` have restrictions regarding column addition. Note that this is constant (in the amount of
+ data the cluster contains) time operation.
+- Remove column(s) from the table. This drops both the column and all its content, but note that while the column
+ becomes immediately unavailable, its content is only removed lazily during compaction. Please also note the warnings
+ below. Due to lazy removal, the altering itself is a constant (in the amount of data removed or contained in the
+ cluster) time operation.
+- Change data type of the column to a compatible type.
+- Change some of the table options (through the ``WITH`` instruction). The :ref:`supported options
+ <create-table-options>` are the same that when creating a table (outside of ``COMPACT STORAGE`` and ``CLUSTERING
+ ORDER`` that cannot be changed after creation). Note that setting any ``compaction`` sub-options has the effect of
+ erasing all previous ``compaction`` options, so you need to re-specify all the sub-options if you want to keep them.
+ The same note applies to the set of ``compression`` sub-options.
+- Change or add any of the ``Encryption options`` above.
+- Change or add any of the :ref:`CDC options <cdc-options>` above.
+
+.. warning:: Dropping a column assumes that the timestamps used for the value of this column are "real" timestamp in
+ microseconds. Using "real" timestamps in microseconds is the default is and is **strongly** recommended, but as
+ Scylla allows the client to provide any timestamp on any table, it is theoretically possible to use another
+ convention. Please be aware that if you do so, dropping a column will not work correctly.
+
+.. warning:: Once a column is dropped, it is allowed to re-add a column with the same name as the dropped one
+ **unless** the type of the dropped column was a (non-frozen) column (due to an internal technical limitation).
+
+
+.. _drop-table-statement:
+
+DROP TABLE
+^^^^^^^^^^
+
+Dropping a table uses the ``DROP TABLE`` statement:
+
+.. code-block::
+
+ drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name`
+
+Dropping a table results in the immediate removal of the table, including all data it contains.
+
+.. include:: /getting-started/_common/note-reclaim-space.rst
+
+If the table does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case the
+operation is a no-op.
+
+.. _truncate-statement:
+
+TRUNCATE
+^^^^^^^^
+
+A table can be truncated using the ``TRUNCATE`` statement:
+
+.. code-block::
+
+ truncate_statement: TRUNCATE [ TABLE ] `table_name`
+
+Note that ``TRUNCATE TABLE foo`` is allowed for consistency with other DDL statements, but tables are the only object
+that can be truncated currently and so the ``TABLE`` keyword can be omitted.
+
+Truncating a table permanently removes all existing data from the table, but without removing the table itself.
+
+.. caution:: Do not run any operation on a table that is being truncated. Truncate operation is an administrative operation, and running any other operation on the same table in parallel may cause the truncating table's data to end up in an undefined state.
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
\ No newline at end of file
diff --git a/docs/getting-started/definitions.rst b/docs/getting-started/definitions.rst
--- a/docs/getting-started/definitions.rst
+++ b/docs/getting-started/definitions.rst
@@ -0,0 +1,226 @@
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+.. highlight:: cql
+
+Definitions
+-----------
+
+.. include:: /rst_include/cql-version-index.rst
+
+.. _conventions:
+
+Conventions
+^^^^^^^^^^^
+
+To aid in specifying the CQL syntax, we will use the following conventions in this document:
+
+- Language rules will be given in an informal `BNF variant
+ <http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form#Variants>`_ notation. In particular, we'll use square brackets
+ (``[ item ]``) for optional items, ``*`` and ``+`` for repeated items (where ``+`` imply at least one).
+- The grammar will also use the following convention for convenience: non-terminal term will be lowercase (and link to
+ their definition) while terminal keywords will be provided "all caps". Note, however, that keywords are
+ :ref:`identifiers` and are thus case insensitive in practice. We will also define some early construction using
+ regexp, which we'll indicate with ``re(<some regular expression>)``.
+- The grammar is provided for documentation purposes and leaves some minor details out. For instance, the comma on the
+ last column definition in a ``CREATE TABLE`` statement is optional but supported if present even though the grammar in
+ this document suggests otherwise. Also, not everything accepted by the grammar is necessarily valid CQL.
+- References to keywords or pieces of CQL code in running text will be shown in a ``fixed-width font``.
+
+
+.. _identifiers:
+
+Identifiers and keywords
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The CQL language uses *identifiers* (or *names*) to identify tables, columns, and other objects. An identifier is a token
+matching the regular expression ``[a-zA-Z][a-zA-Z0-9_]*``.
+
+A number of such identifiers, like ``SELECT`` or ``WITH``, are *keywords*. They have a fixed meaning for the language,
+and most are reserved. The list of those keywords can be found in :ref:`appendix-A`.
+
+Identifiers and (unquoted) keywords are case insensitive. Thus ``SELECT`` is the same as ``select`` or ``sElEcT``, and
+``myId`` is the same than ``myid`` or ``MYID``. A convention often used (in particular by the samples of this
+documentation) is to use upper case for keywords and lower case for other identifiers.
+
+There is a second kind of identifier called *quoted identifiers*, defined by enclosing an arbitrary sequence of
+characters (non-empty) in double-quotes(``"``). Quoted identifiers are never keywords. Thus ``"select"`` is not a
+reserved keyword and can be used to refer to a column (note that using this is particularly advised), while ``select``
+would raise a parsing error. Also, contrary to unquoted identifiers and keywords, quoted identifiers are case
+sensitive (``"My Quoted Id"`` is *different* from ``"my quoted id"``). A fully lowercase quoted identifier that matches
+``[a-zA-Z][a-zA-Z0-9_]*`` is, however, *equivalent* to the unquoted identifier obtained by removing the double-quote (so
+``"myid"`` is equivalent to ``myid`` and to ``myId`` but different from ``"myId"``). Inside a quoted identifier, the
+double-quote character can be repeated to escape it, so ``"foo "" bar"`` is a valid identifier.
+
+.. note:: *quoted identifiers* allow to declare columns with arbitrary names, and those can sometimes clash with
+ specific names used by the server. For instance, when using a conditional update, the server will respond with a
+ result-set containing a special result named ``"[applied]"``. If you’ve declared a column with such a name, this
+ could potentially confuse some tools and should be avoided. In general, unquoted identifiers should be preferred, but
+ if you use quoted identifiers, it is strongly advised to avoid any name enclosed by squared brackets (like
+ ``"[applied]"``) and any name that looks like a function call (like ``"f(x)"``).
+
+More formally, we have:
+
+.. code-block::
+
+ identifier: `unquoted_identifier` | `quoted_identifier`
+ unquoted_identifier: re('[a-zA-Z][a-zA-Z0-9_]*')
+ quoted_identifier: '"' (any character where " can appear if doubled)+ '"'
+
+.. _constants:
+
+Constants
+^^^^^^^^^
+
+CQL defines the following kind of *constants*:
+
+.. code-block:: none
+
+ constant: `string` | `integer` | `float` | `boolean` | `uuid` | `blob` | NULL
+
+ string: '\'' (any character where ' can appear if doubled)+ '\''
+ : '$$' (any character other than '$$') '$$'
+
+ integer: re('-?[0-9]+')
+
+ float: re('-?[0-9]+(\.[0-9]*)?([eE][+-]?[0-9+])?') | NAN | INFINITY
+
+ boolean: TRUE | FALSE
+
+ uuid: `hex`{8}-`hex`{4}-`hex`{4}-`hex`{4}-`hex`{12}
+
+ hex: re("[0-9a-fA-F]")
+
+ blob: '0' ('x' | 'X') `hex`+
+
+In other words:
+
+- A string constant is an arbitrary sequence of characters enclosed by single-quote(``'``). A single-quote
+ can be included by repeating it, e.g. ``'It''s raining today'``. Those are not to be confused with quoted
+ :ref:`identifiers` that use double-quotes. Alternatively, a string can be defined by enclosing the arbitrary sequence
+ of characters by two dollar characters, in which case single-quote can be used without escaping (``$$It's raining
+ today$$``). That latter form is often used when defining user-defined functions to avoid having to
+ escape single-quote characters in function body (as they are more likely to occur than ``$$``).
+- Integer, float, and boolean constant are defined as expected. Note, however, than float allows the special ``NaN`` and
+ ``Infinity`` constants.
+- CQL supports UUID_ constants.
+- Blob content types are provided in hexadecimal and prefixed by ``0x``.
+- The special ``NULL`` constant denotes the absence of value.
+
+For how these constants are typed, see the :doc:`data-types <types>` document.
+
+Terms
+^^^^^
+
+CQL has the notion of a *term*, which denotes the kind of values that CQL support. Terms are defined by:
+
+.. code-block:: cql
+
+ term: `constant` | `literal` | `function_call` | `arithmetic_operation` | `type_hint` | `bind_marker`
+
+ literal: `collection_literal` | `udt_literal` | `tuple_literal`
+
+ function_call: `identifier` '(' [ `term` (',' `term`)* ] ')'
+
+ arithmetic_operation: '-' `term` | `term` ('+' | '-' | '*' | '/' | '%') `term`
+
+ type_hint: '(' `cql_type` `)` term
+
+ bind_marker: '?' | ':' `identifier`
+
+A term is thus one of:
+
+- A :ref:`constant <constants>`.
+- A literal for either :ref:`a collection <collections>`, a user-defined type or a tuple
+ (see the linked sections for details).
+- An arithmetic operation between terms.
+- A *type hint*
+- A bind marker, which denotes a variable to be bound at execution time. See the section on :ref:`prepared-statements`
+ for details. A bind marker can be either anonymous (``?``) or named (``:some_name``). The latter form provides a more
+ convenient way to refer to the variable for binding it and should generally be preferred.
+
+
+Comments
+^^^^^^^^
+
+A comment in CQL is a line beginning by either double dashes (``--``) or double slash (``//``).
+
+Multi-line comments are also supported through enclosure within ``/*`` and ``*/`` (but nesting is not supported).
+
+::
+
+ -- This is a comment
+ // This is a comment too
+ /* This is
+ a multi-line comment */
+
+Statements
+^^^^^^^^^^
+
+CQL consists of statements that can be divided into the following categories:
+
+- :doc:`Data Definition </getting-started/ddl/>` statements - to define and change how the data is stored (keyspaces and tables).
+- :doc:`Data Manipulation </getting-started/dml/>` statements - for selecting, inserting and deleting data.
+- :ref:`cql-permissions` statements.
+- cql-triggers statements.
+
+All the statements are listed below and are described in the rest of this documentation (see links above):
+
+.. code-block:: cql
+
+ cql_statement: `statement` [ ';' ]
+ statement: `ddl_statement`
+ : | `dml_statement`
+ : | `secondary_index_statement`
+ : | `materialized_view_statement`
+ : | `role_or_permission_statement`
+ : | `udf_statement`
+ : | `udt_statement`
+ : | `trigger_statement`
+ ddl_statement: `use_statement`
+ : | `create_keyspace_statement`
+ : | `alter_keyspace_statement`
+ : | `drop_keyspace_statement`
+ : | `create_table_statement`
+ : | `alter_table_statement`
+ : | `drop_table_statement`
+ : | `truncate_statement`
+ dml_statement: `select_statement`
+ : | `insert_statement`
+ : | `update_statement`
+ : | `delete_statement`
+ : | `batch_statement`
+ trigger_statement: `create_trigger_statement`
+ : | `drop_trigger_statement`
+
+.. _prepared-statements:
+
+Prepared Statements
+^^^^^^^^^^^^^^^^^^^
+
+CQL supports *prepared statements*. Prepared statements are an optimization that allows parsing a query only once but
+executes it multiple times with different concrete values.
+
+Any statement that uses at least one bind marker (see :token:`bind_marker`) will need to be *prepared*. After which, the statement
+can be *executed* by provided concrete values for each of its markers. The exact details of how a statement is prepared
+and then executed depends on the CQL driver used, and you should refer to your driver documentation.
+
+
+.. include:: /rst_include/apache-copyrights-index.rst
+.. include:: /rst_include/apache-cql-return-index.rst
diff --git a/docs/getting-started/dml.rst b/docs/getting-started/dml.rst
--- a/docs/getting-started/dml.rst
+++ b/docs/getting-started/dml.rst
@@ -0,0 +1,974 @@
+.. highlight:: cql
+
+Data Manipulation
+-----------------
+
+.. include:: /rst_include/cql-version-index.rst
+
+This section describes the statements supported by CQL to insert, update, delete, and query data.
+
+:ref:`SELECT <select-statement>`
+
+.. _select:
+
+:ref:`INSERT <insert-statement>`
+
+.. _insert:
+
+:ref:`UPDATE <update-statement>`
+
+.. _update:
+
+:ref:`DELETE <delete_statement>`
+
+.. _delete:
+
+:ref:`BATCH <batch_statement>`
+
+.. _batch:
+
+
+.. _select-statement:
+
+SELECT
+^^^^^^
+
+Querying data from data is done using a ``SELECT`` statement:
+
+.. code-block::
+
+ select_statement: SELECT [ DISTINCT ] ( `select_clause` | '*' )
+ : FROM `table_name`
+ : [ WHERE `where_clause` ]
+ : [ GROUP BY `group_by_clause` ]
+ : [ ORDER BY `ordering_clause` ]
+ : [ PER PARTITION LIMIT (`integer` | `bind_marker`) ]
+ : [ LIMIT (`integer` | `bind_marker`) ]
+ : [ ALLOW FILTERING ]
+ : [ BYPASS CACHE ]
+ : [ USING TIMEOUT `timeout` ]
+ select_clause: `selector` [ AS `identifier` ] ( ',' `selector` [ AS `identifier` ] )*
+ selector: `column_name`
+ : | CAST '(' `selector` AS `cql_type` ')'
+ : | `function_name` '(' [ `selector` ( ',' `selector` )* ] ')'
+ : | COUNT '(' '*' ')'
+ where_clause: `relation` ( AND `relation` )*
+ relation: `column_name` `operator` `term`
+ : '(' `column_name` ( ',' `column_name` )* ')' `operator` `tuple_literal`
+ : TOKEN '(' `column_name` ( ',' `column_name` )* ')' `operator` `term`
+ operator: '=' | '<' | '>' | '<=' | '>=' | IN | CONTAINS | CONTAINS KEY
+ ordering_clause: `column_name` [ ASC | DESC ] ( ',' `column_name` [ ASC | DESC ] )*
+ timeout: `duration`
+
+For instance::
+
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207);
+ SELECT name AS user_name, occupation AS user_occupation FROM users;
+
+ SELECT time, value
+ FROM events
+ WHERE event_type = 'myEvent'
+ AND time > '2011-02-03'
+ AND time <= '2012-01-01'
+
+ SELECT COUNT (*) AS user_count FROM users;
+
+ SELECT * FROM users WHERE event_type = 'myEvent' USING TIMEOUT 50ms;
+
+The ``SELECT`` statement reads one or more columns for one or more rows in a table. It returns a result-set of the rows
+matching the request, where each row contains the values for the selection corresponding to the query. Additionally,
+functions, including aggregation ones, can be applied to the result.
+
+A ``SELECT`` statement contains at least a :ref:`selection clause <selection-clause>` and the name of the table on which
+the selection is on (note that CQL does **not** support joins or sub-queries, and thus a select statement only applies to a single
+table). In most cases, a select will also have a :ref:`where clause <where-clause>` and it can optionally have additional
+clauses to :ref:`order <ordering-clause>` or :ref:`limit <limit-clause>` the results. Lastly, :ref:`queries that require
+filtering <allow-filtering>` can be allowed if the ``ALLOW FILTERING`` flag is provided.
+
+If your ``SELECT`` query results in what appears to be missing data, see this :doc:`KB Article </kb/cqlsh-results>` for information.
+
+.. _selection-clause:
+
+Selection clause
+~~~~~~~~~~~~~~~~
+
+The :token:`select_clause` determines which columns need to be queried and returned in the result-set, as well as any
+transformation to apply to this result before returning. It consists of a comma-separated list of *selectors* or,
+alternatively, of the wildcard character (``*``) to select all the columns defined in the table.
+
+Selectors
+`````````
+
+A :token:`selector` can be one of:
+
+- A column name of the table selected to retrieve the values for that column.
+- A casting, which allows you to convert a nested selector to a (compatible) type.
+- A function call, where the arguments are selector themselves.
+
+Aliases
+```````
+
+Every *top-level* selector can also be aliased (using `AS`). If so, the name of the corresponding column in the result
+set will be that of the alias. For instance::
+
+ // Without alias
+ SELECT intAsBlob(4) FROM t;
+
+ // intAsBlob(4)
+ // --------------
+ // 0x00000004
+
+ // With alias
+ SELECT intAsBlob(4) AS four FROM t;
+
+ // four
+ // ------------
+ // 0x00000004
+
+.. note:: Currently, aliases aren't recognized anywhere else in the statement where they are used (not in the ``WHERE``
+ clause, not in the ``ORDER BY`` clause, ...). You must use the original column name instead.
+
+
+``WRITETIME`` and ``TTL`` function
+```````````````````````````````````
+
+Selection supports two special functions (which aren't allowed anywhere else): ``WRITETIME`` and ``TTL``. Both functions
+take only one argument, and that argument *must* be a column name (so, for instance, ``TTL(3)`` is invalid).
+
+Those functions let you retrieve meta-information that is stored internally for each column, namely:
+
+- ``WRITETIME`` retrieves the timestamp used when writing the column. The timestamp is typically the number of *microseconds* since the `Unix epoch <https://en.wikipedia.org/wiki/Unix_time>`_ (January 1st 1970 at 00:00:00 UTC).
+
+You can read more about the ``TIMESTAMP`` retrieved by ``WRITETIME`` in the :ref:`UPDATE <update-parameters>` section.
+
+- ``TTL`` retrieves the remaining time to live (in *seconds*) for the value of the column, if it set to expire, or ``null`` otherwise.
+
+You can read more about TTL in the :doc:`documentation </getting-started/time-to-live>` and also in `this Scylla University lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`.
+
+.. _where-clause:
+
+The ``WHERE`` clause
+~~~~~~~~~~~~~~~~~~~~
+
+The ``WHERE`` clause specifies which rows must be queried. It is composed of relations on the columns that are part of
+the ``PRIMARY KEY``.
+
+Not all relations are allowed in a query. For instance, non-equal relations (where ``IN`` is considered as an equal
+relation) on a partition key are not supported (see the use of the ``TOKEN`` method below to do non-equal queries on
+the partition key). Moreover, for a given partition key, the clustering columns induce an ordering of rows and relations
+on them restricted to the relations that let you select a **contiguous** (for the ordering) set of rows. For
+instance, given::
+
+ CREATE TABLE posts (
+ userid text,
+ blog_title text,
+ posted_at timestamp,
+ entry_title text,
+ content text,
+ category int,
+ PRIMARY KEY (userid, blog_title, posted_at)
+ )
+
+The following query is allowed::
+
+ SELECT entry_title, content FROM posts
+ WHERE userid = 'john doe'
+ AND blog_title='John''s Blog'
+ AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31'
+
+But the following query is not, as it does not select a contiguous set of rows (and we suppose no secondary indexes are
+set)::
+
+ // Needs a blog_title to be set to select ranges of posted_at
+ SELECT entry_title, content FROM posts
+ WHERE userid = 'john doe'
+ AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31'
+
+When specifying relations, the ``TOKEN`` function can be used on the ``PARTITION KEY`` column to query. In that case,
+rows will be selected based on the token of their ``PARTITION_KEY`` rather than on the value. Note that the token of a
+key depends on the partitioner in use and that, in particular, the RandomPartitioner won't yield a meaningful order. Also
+note that ordering partitioners always order token values by bytes (so even if the partition key is of type int,
+``token(-1) > token(0)`` in particular). For example::
+
+ SELECT * FROM posts
+ WHERE token(userid) > token('tom') AND token(userid) < token('bob')
+
+Moreover, the ``IN`` relation is only allowed on the last column of the partition key and on the last column of the full
+primary key.
+
+It is also possible to “group” ``CLUSTERING COLUMNS`` together in a relation using the tuple notation. For instance::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND (blog_title, posted_at) > ('John''s Blog', '2012-01-01')
+
+will request all rows that sort after the one having “John's Blog” as ``blog_title`` and '2012-01-01' for ``posted_at``
+in the clustering order. In particular, rows having a ``post_at <= '2012-01-01'`` will be returned as long as their
+``blog_title > 'John''s Blog'``, which would not be the case for::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND blog_title > 'John''s Blog'
+ AND posted_at > '2012-01-01'
+
+The tuple notation may also be used for ``IN`` clauses on clustering columns::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND (blog_title, posted_at) IN (('John''s Blog', '2012-01-01'), ('Extreme Chess', '2014-06-01'))
+
+The ``CONTAINS`` operator may only be used on collection columns (lists, sets, and maps). In the case of maps,
+``CONTAINS`` applies to the map values. The ``CONTAINS KEY`` operator may only be used on map columns and applies to the
+map keys.
+
+.. _group-by-clause:
+
+Grouping results
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The ``GROUP BY`` option lets you condense into a single row all selected rows that share the same values for a set of columns.
+Using the ``GROUP BY`` option, it is only possible to group rows at the partition key level or at a clustering column level.
+The ``GROUP BY`` arguments must form a prefix of the primary key.
+
+For example, if the primary key is ``(p1, p2, c1, c2)``, then the following queries are valid::
+
+ GROUP BY p1
+ GROUP BY p1, p2
+ GROUP BY p1, p2, c1
+ GROUP BY p1, p2, c1, c2
+
+The following should be considered when using the ``GROUP BY`` option:
+
+* If a primary key column is restricted by an equality restriction, it is not required to be present in the ``GROUP BY`` clause.
+
+* Aggregate functions will produce a separate value for each group.
+
+* If no ``GROUP BY`` clause is specified, aggregate functions will produce a single value for all the rows.
+
+* If a column is selected without an aggregate function, in a statement with a ``GROUP BY``, the first value encounter in each group will be returned.
+
+
+.. _ordering-clause:
+
+Ordering results
+~~~~~~~~~~~~~~~~
+
+The ``ORDER BY`` clause lets you select the order of the returned results. It takes as argument a list of column names
+along with the order for the column (``ASC`` for ascendant and ``DESC`` for descendant, omitting the order being
+equivalent to ``ASC``). Currently, the possible orderings are limited by the :ref:`clustering order <clustering-order>`
+defined on the table:
+
+- If the table has been defined without any specific ``CLUSTERING ORDER``, then allowed orderings are the order
+ induced by the clustering columns and the reverse of that one.
+- Otherwise, the orderings allowed are the order of the ``CLUSTERING ORDER`` option and the reversed one.
+
+.. _limit-clause:
+
+Limiting results
+~~~~~~~~~~~~~~~~
+
+.. versionchanged:: 3.1 Scylla Open Source
+
+The ``LIMIT`` option to a ``SELECT`` statement limits the number of rows returned by a query, while the ``PER PARTITION
+LIMIT`` option (introduced in Scylla 3.1) limits the number of rows returned for a given **partition** by the query. Note that both types of limit can be
+used in the same statement.
+
+Examples:
+
+The Partition Key in the following table is ``client_id``, and the clustering key is ``when``.
+The table has seven rows, split between four clients (partition keys)
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM test;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 2 | 2020-02-11 22:00:00.000000+0000
+ 2 | 2020-02-12 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (7 rows)
+
+
+You can ask the query to limit the number of rows returned from **all partition** with LIMIT, for example:
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test LIMIT 3;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+
+ (3 rows)
+
+You can ask the query to limit the number of rows returned for **each** ``client_id``. For example, with limit of *1* :
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 1;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (4 rows)
+
+Increasing limit to *2*, would yield:
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 2;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 2 | 2020-02-11 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (6 rows)
+
+You can also mix the two limits types:
+
+.. code-block:: cql
+
+ cqlsh> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 1 LIMIT 3;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+
+ (3 rows)
+
+
+.. _allow-filtering:
+
+Allowing filtering
+~~~~~~~~~~~~~~~~~~
+
+By default, CQL only allows select queries that don't involve “filtering” server-side, i.e. queries where we know that
+all (live) record read will be returned (maybe partly) in the result set. The reasoning is that those “non filtering”
+queries have predictable performance in the sense that they will execute in a time that is proportional to the amount of
+data **returned** by the query (which can be controlled through ``LIMIT``).
+
+The ``ALLOW FILTERING`` option lets you explicitly allow (some) queries that require filtering. Please note that a
+query using ``ALLOW FILTERING`` may thus have unpredictable performance (for the definition above), i.e. even a query
+that selects a handful of records **may** exhibit performance that depends on the total amount of data stored in the
+cluster.
+
+For instance, consider the following table holding user profiles with their year of birth (with a secondary index on
+it) and country of residence::
+
+ CREATE TABLE users (
+ username text PRIMARY KEY,
+ firstname text,
+ lastname text,
+ birth_year int,
+ country text
+ )
+
+ CREATE INDEX ON users(birth_year);
+
+Then the following queries are valid::
+
+ SELECT * FROM users;
+ SELECT * FROM users WHERE birth_year = 1981;
+
+because in both cases, Scylla guarantees that these queries' performance will be proportional to the amount of data
+returned. In particular, if no users were born in 1981, then the second query performance will not depend on the number
+of user profiles stored in the database (not directly at least: due to secondary index implementation consideration, this
+query may still depend on the number of nodes in the cluster, which indirectly depends on the amount of data stored.
+Nevertheless, the number of nodes will always be multiple orders of magnitude lower than the number of user profiles
+stored). Of course, both queries may return very large result sets in practice, but the amount of data returned can always
+be controlled by adding a ``LIMIT``.
+
+However, the following query will be rejected::
+
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR';
+
+because Scylla cannot guarantee that it won't have to scan a large amount of data even if the result of those queries is
+small. Typically, it will scan all the index entries for users born in 1981 even if only a handful are actually from
+France. However, if you “know what you are doing”, you can force the execution of this query by using ``ALLOW
+FILTERING`` and so the following query is valid::
+
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING;
+
+.. _bypass-cache:
+
+Bypass Cache
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: Scylla Enterprise 2019.1.1
+.. versionadded:: Scylla 3.1
+
+
+The ``BYPASS CACHE`` clause on SELECT statements informs the database that the data being read is unlikely to be read again in the near future, and also was unlikely to have been read in the near past; therefore, no attempt should be made to read it from the cache or to populate the cache with the data. This is mostly useful for range scans; these typically process large amounts of data with no temporal locality and do not benefit from the cache.
+The clause is placed immediately after the optional ALLOW FILTERING clause.
+
+``BYPASS CACHE`` is a Scylla CQL extension and not part of Apache Cassandra CQL.
+
+For example::
+
+ SELECT * FROM users BYPASS CACHE;
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207) BYPASS CACHE;
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING BYPASS CACHE;
+
+.. _using-timeout:
+
+Using Timeout
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: Scylla 4.4
+
+The ``USING TIMEOUT`` clause allows specifying a timeout for a specific request.
+
+For example::
+
+ SELECT * FROM users USING TIMEOUT 5s;
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207) BYPASS CACHE USING TIMEOUT 200ms;
+
+``USING TIMEOUT`` is a Scylla CQL extension and not part of Apache Cassandra CQL.
+
+.. _like-operator:
+
+LIKE Operator
+~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The ``LIKE`` operation on ``SELECT`` statements informs Scylla that you are looking for a pattern match. The expression ‘column LIKE pattern’ yields true only if the entire column value matches the pattern.
+
+The search pattern is a string of characters with two wildcards, as shown:
+
+* ``_`` matches any single character
+* ``%`` matches any substring (including an empty string)
+* ``\`` escapes the next pattern character, so it matches verbatim
+* any other pattern character matches itself
+* an empty pattern matches empty text fields
+
+
+.. note:: Only string types (ascii, text, and varchar) are valid for matching
+
+Currently, the match is **case sensitive**. The entire column value must match the pattern.
+For example, consider the search pattern 'M%n' - this will match ``Martin``, but will not match ``Moonbeam`` because the ``m`` at the end isn't matched. In addition, ``moon`` is not matched because ``M`` is not the same as ``m``. Both the pattern and the column value are assumed to be UTF-8 encoded.
+
+A query can find all values containing some text fragment by matching to an appropriate ``LIKE`` pattern.
+
+**Differences Between Scylla and Cassandra LIKE Operators**
+
+* In Apache Cassandra, you must create a SASI index to use LIKE. Scylla supports LIKE as a regular filter.
+* Consequently, Scylla LIKE will be less performant than Apache Cassandra LIKE for some workloads.
+* Scylla treats underscore (_) as a wildcard; Cassandra doesn't.
+* Scylla treats percent (%) as a wildcard anywhere in the pattern; Cassandra only at the beginning/end
+* Scylla interprets backslash (\\) as an escape character; Cassandra doesn't.
+* Cassandra allows case-insensitive LIKE; Scylla doesn't (see `#4911 <https://github.com/scylladb/scylla/issues/4911>`_).
+* Scylla allows empty LIKE pattern; Cassandra doesn't.
+
+**Example A**
+
+In this example, ``LIKE`` specifies that the match is looking for a word that starts with the letter ``S``. The ``%`` after the letter ``S`` matches any text to the end of the field.
+
+.. code-block:: none
+
+ SELECT * FROM pet_owners WHERE firstname LIKE ‘S%’ ALLOW FILTERING;
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │1 │Adams │Steven │
+ ├──────────┼─────────────────────┼────────────────┤
+ │15 │Erg │Sylvia │
+ ├──────────┼─────────────────────┼────────────────┤
+ │20 │Goldberg │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │25 │Harris │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │88 │Rosenberg │Samuel │
+ ├──────────┼─────────────────────┼────────────────┤
+ │98 │Smith │Sara │
+ ├──────────┼─────────────────────┼────────────────┤
+ │115 │Williams │Susan │
+ ├──────────┼─────────────────────┼────────────────┤
+ │130 │Young │Stuart │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+
+
+
+**Example B**
+
+In this example, you are searching for all pet owners whose last name contains the characters 'erg'.
+
+.. code-block:: none
+
+ SELECT * FROM pet_owners WHERE lastname LIKE ‘%erg%’ ALLOW FILTERING;
+
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │11 │Berger │David │
+ ├──────────┼─────────────────────┼────────────────┤
+ │18 │Gerg │Lawrence │
+ ├──────────┼─────────────────────┼────────────────┤
+ │20 │Goldberg │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │88 │Rosenberg │Samuel │
+ ├──────────┼─────────────────────┼────────────────┤
+ │91 │Schulberg │Barry │
+ ├──────────┼─────────────────────┼────────────────┤
+ │110 │Weinberg │Stuart │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+Note that this query does not return:
+
+.. code-block:: none
+
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │15 │Erg │Sylvia │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+As it is case sensitive.
+
+
+**Example C**
+
+This table contains some commonly used ``LIKE`` filters and the matches you can expect the filter to return.
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Filter
+ - Matches
+ * - %abe%
+ - Babel, aberration, cabernet, scarabees
+ * - _0\%
+ - 10%, 20%, 50%
+ * - a%t
+ - asphalt, adapt, at
+
+.. _insert-statement:
+
+INSERT
+^^^^^^
+
+Inserting data for a row is done using an ``INSERT`` statement:
+
+.. code-block::
+
+ insert_statement: INSERT INTO table_name ( `names_values` | `json_clause` )
+ : [ IF NOT EXISTS ]
+ : [ USING `update_parameter` ( AND `update_parameter` )* ];
+ names_values: `names` VALUES `tuple_literal`
+ json_clause: JSON `string` [ DEFAULT ( NULL | UNSET ) ]
+ names: '(' `column_name` ( ',' `column_name` )* ')'
+ update_parameter: ( TIMESTAMP `int_value` | TTL `int_value` | TIMEOUT `duration` )
+ int_value: ( `integer` | `bind_marker` )
+
+For example:
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor, year)
+ VALUES ('Serenity', 'Joss Whedon', 'Nathan Fillion', 2005)
+ USING TTL 86400 IF NOT EXISTS;
+
+The ``INSERT`` statement writes one or more columns for a given row in a table. Note that since a row is identified by
+its ``PRIMARY KEY``, at least the columns composing it must be specified. The list of columns to insert to must be
+supplied when using the ``VALUES`` syntax.
+
+Note that unlike in SQL, ``INSERT`` does not check the prior existence of the row by default: the row is created if none
+existed before, and updated otherwise. Furthermore, there is no means to know which of creation or update happened.
+
+All updates of an ``INSERT`` are applied atomically, meaning the
+statement can not have a partial effect on database state.
+
+It can, however, leave some of the columns unchanged due to the semantics
+of eventual consistency on an event of a timestamp collision:
+
+``INSERT`` statements happening concurrently at different cluster
+nodes proceed without coordination. Eventually cell values
+supplied by a statement with the highest timestamp will prevail.
+
+Unless a timestamp is provided by the client, Scylla will automatically
+generate a timestamp with microsecond precision for each
+column assigned by ``INSERT``. Scylla ensures timestamps created
+by the same node are unique. Timestamps assigned at different
+nodes are not guaranteed to be globally unique.
+With a steadily high write rate timestamp collision
+is not unlikely. If it happens, i.e. two ``INSERTS`` have the same
+timestamp, the lexicographically bigger value prevails:
+
+Please refer to the :ref:`UPDATE <update-parameters>` section for more information on the :token:`update_parameter`.
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Anonymous', 'Unknown')
+ USING TIMESTAMP 1442880000000000;
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Joseph Whedon', 'Nathan Fillion')
+ USING TIMESTAMP 1442880000000000;
+
+ SELECT movie, director, main_actor FROM NerdMovies WHERE movie = 'Serenity'
+
+.. code-block:: none
+
+ movie | director | main_actor | year
+ ----------+---------------+------------+------
+ Serenity | Joseph Whedon | Unknown | null
+
+
+``INSERT`` is not required to assign all columns, so if two
+statements modify the same primary key but assign different
+columns effects of both statements are preserved:
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Joss Whedon', 'Nathan Fillion');
+ INSERT INTO NerdMovies (movie, director, main_actor, year)
+ VALUES ('Serenity', 'Josseph Hill Whedon', 2005);
+ SELECT * FROM NerdMovies WHERE movie = 'Serenity'
+
+.. code-block:: none
+
+ ╭─────────┬───────────────────┬──────────────┬─────╮
+ │movie │director │main_actor │year │
+ ├─────────┼───────────────────┼──────────────┼─────┤
+ │Serenity │Joseph Hill Whedon │Nathan Fillion│2005 │
+ ╰─────────┴───────────────────┴──────────────┴─────╯
+
+Also note that ``INSERT`` does not support counters, while ``UPDATE`` does.
+
+.. note:: New in Scylla Open Source 3.2, you can use the ``IF NOT EXISTS`` condition with the ``INSERT`` statement. When this is used, the insert is only made if the row does not exist prior to the insertion. Each such ``INSERT`` gets a globally unique timestamp. Using ``IF NOT EXISTS`` incurs a non-negligible performance cost (internally, as Paxos will be used), so use ``IF NOT EXISTS`` wisely.
+
+
+Starting with Scylla Open Source 3.2, if :ref:`enabled <cdc-options>` on a table, you can use UPDATE, INSERT, and DELETE statements with Change Data Capture (CDC) tables. Note that this feature is :ref:`experimental <yaml_enabling_experimental_features>` in version 3.2.
+
+.. to-do - add link to cdc doc
+
+.. _update-statement:
+
+UPDATE
+^^^^^^
+
+Updating a row is done using an ``UPDATE`` statement:
+
+.. code-block::
+
+ update_statement: UPDATE `table_name`
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : SET `assignment` ( ',' `assignment` )*
+ : WHERE `where_clause`
+ : [ IF ( EXISTS | `condition` ( AND `condition` )*) ]
+ update_parameter: ( TIMESTAMP `int_value` | TTL `int_value` | TIMEOUT `duration` )
+ int_value: ( `integer` | `bind_marker` )
+ assignment: `simple_selection` '=' `term`
+ : | `column_name` '=' `column_name` ( '+' | '-' ) `term`
+ : | `column_name` '=' `list_literal` '+' `column_name`
+ simple_selection: `column_name`
+ : | `column_name` '[' `term` ']'
+ : | `column_name` '.' `field_name`
+ condition: `simple_selection` `operator` `term`
+
+For instance:
+
+.. code-block:: cql
+
+ UPDATE NerdMovies USING TTL 400
+ SET director = 'Joss Whedon',
+ main_actor = 'Nathan Fillion',
+ year = 2005
+ WHERE movie = 'Serenity';
+
+ UPDATE UserActions
+ SET total = total + 2
+ WHERE user = B70DE1D0-9908-4AE3-BE34-5573E5B09F14
+ AND action = 'click';
+
+The ``UPDATE`` statement writes one or more columns for a given row in a table. The :token:`where_clause` is used to
+select the row to update and must include all columns composing the ``PRIMARY KEY``. Non-primary key columns are then
+set using the ``SET`` keyword.
+
+Note that unlike in SQL, ``UPDATE`` does not check the prior existence of the row by default,
+
+(except through IF_, see below):
+
+the row is created if none existed before, and updated otherwise. Furthermore, there is no way to know
+whether creation or update occurred.
+
+In an ``UPDATE`` statement, all updates within the same partition key are applied atomically,
+meaning either all provided values are stored or none at all.
+
+Similarly to ``INSERT``, ``UPDATE`` statement happening concurrently at different
+cluster nodes proceed without coordination. Cell values
+supplied by a statement with the highest timestamp will prevail.
+If two ``UPDATE`` statements or ``UPDATE`` and ``INSERT``
+statements have the same timestamp,
+lexicographically bigger value prevails.
+
+Regarding the :token:`assignment`:
+
+- ``c = c + 3`` is used to increment/decrement counters. The column name after the '=' sign **must** be the same as
+ the one before the '=' sign. Note that increment/decrement is only allowed on counters, and are the *only* update
+ operations allowed on counters. See the section on :ref:`counters <counters>` for details.
+- ``id = id + <some-collection>`` and ``id[value1] = value2`` are for collections, see the :ref:`relevant section
+ <collections>` for details.
+- ``id.field = 3`` is for setting the value of a field on non-frozen user-defined types.
+
+.. _IF:
+
+IF condition
+~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+It is, however, possible to use the conditions on some columns through ``IF``, in which case the row will not be updated
+unless the conditions are met. Each such ``UPDATE`` gets a globally unique timestamp.
+But, please note that using ``IF`` conditions will incur a non-negligible performance
+cost (internally, Paxos will be used), so this should be used sparingly.
+
+
+.. _update-parameters:
+
+Update parameters
+~~~~~~~~~~~~~~~~~
+
+The ``UPDATE``, ``INSERT`` (and ``DELETE`` and ``BATCH`` for the ``TIMESTAMP``) statements support the following
+parameters:
+
+- ``TIMESTAMP``: sets the timestamp for the operation. If not specified, the coordinator will use the current time, in
+ *microseconds* since the `Unix epoch <https://en.wikipedia.org/wiki/Unix_time>`_ (January 1st 1970 at 00:00:00 UTC),
+ at the start of statement execution as the timestamp. This is usually a suitable default.
+ :ref:`INSERT <insert-statement>`, :ref:`UPDATE <update-statement>`, :ref:`DELETE <delete_statement>`, or :ref:`BATCH <batch_statement>`
+ statements ``USING TIMESTAMP`` should provide a unique timestamp value, similar to the one
+ implicitly set by the coordinator by default, when the `USING TIMESTAMP` update parameter is absent.
+ Scylla ensures that query timestamps created by the same coordinator node are unique (even across different shards
+ on the same node). However, timestamps assigned at different nodes are not guaranteed to be globally unique.
+ Note that with a steadily high write rate, timestamp collision is not unlikely. If it happens, e.g. two INSERTS
+ have the same timestamp, conflicting cell values are compared and the cells with the lexicographically bigger value prevail.
+- ``TTL``: specifies an optional Time To Live (in seconds) for the inserted values. If set, the inserted values are
+ automatically removed from the database after the specified time. Note that the TTL concerns the inserted values, not
+ the columns themselves. This means that any subsequent update of the column will also reset the TTL (to whatever TTL
+ is specified in that update). By default, values never expire. A TTL of 0 is equivalent to no TTL. If the table has a
+ default_time_to_live, a TTL of 0 will remove the TTL for the inserted or updated values. A TTL of ``null`` is equivalent
+ to inserting with a TTL of 0. You can read more about TTL in the :doc:`documentation </getting-started/time-to-live>` and also in `this Scylla University lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`.
+- ``TIMEOUT``: specifies a timeout duration for the specific request.
+ Please refer to the :ref:`SELECT <using-timeout>` section for more information.
+
+.. _delete_statement:
+
+DELETE
+^^^^^^
+
+Deleting rows or parts of rows uses the ``DELETE`` statement:
+
+.. code-block::
+
+ delete_statement: DELETE [ `simple_selection` ( ',' `simple_selection` ) ]
+ : FROM `table_name`
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : WHERE `where_clause`
+ : [ IF ( EXISTS | `condition` ( AND `condition` )* ) ]
+
+For instance:
+
+.. code-block:: cql
+
+ DELETE FROM NerdMovies USING TIMESTAMP 1240003134000000
+ WHERE movie = 'Serenity';
+
+ DELETE phone FROM Users
+ WHERE userid IN (C73DE1D3-AF08-40F3-B124-3FF3E5109F22, B70DE1D0-9908-4AE3-BE34-5573E5B09F14);
+
+The ``DELETE`` statement deletes columns and rows. If column names are provided directly after the ``DELETE`` keyword,
+only those columns are deleted from the row indicated by the ``WHERE`` clause. Otherwise, whole rows are removed.
+
+The ``WHERE`` clause specifies which rows are to be deleted. Multiple rows may be deleted with one statement by using an
+``IN`` operator. A range of rows may be deleted using an inequality operator (such as ``>=``).
+
+``DELETE`` supports the ``TIMESTAMP`` option with the same semantics as the TIMESTAMP parameter used in the ``UPDATE`` statement.
+The ``DELETE`` statement deletes data written with :ref:`INSERT <insert-statement>` or :ref:`UPDATE <update-statement>` (or :ref:`BATCH <batch_statement>`)
+using a timestamp that is less than or equal to the ``DELETE`` timestamp.
+For more information on the :token:`update_parameter` refer to the :ref:`UPDATE <update-parameters>` section.
+
+In a ``DELETE`` statement, all deletions within the same partition key are applied atomically,
+meaning either all columns mentioned in the statement are deleted or none.
+If ``DELETE`` statement has the same timestamp as ``INSERT`` or
+``UPDATE`` of the same primary key, delete operation prevails.
+
+A ``DELETE`` operation can be conditional through the use of an ``IF`` clause, similar to ``UPDATE`` and ``INSERT``
+statements. Each such ``DELETE`` gets a globally unique timestamp.
+However, as with ``INSERT`` and ``UPDATE`` statements, this will incur a non-negligible performance cost
+(internally, Paxos will be used) and so should be used sparingly.
+
+
+Range deletions
+~~~~~~~~~~~~~~~
+
+Range deletions allow you to delete rows from a single partition, given that the clustering key is within the given range. The delete request can be determined on both ends, or it can be open-ended.
+
+.. _open-range-deletions:
+
+
+Open range deletions
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+Open range deletions delete rows based on an open-ended request (>, <, >=, =<, etc.)
+
+For example, suppose your data set for events at Madison Square Garden includes:
+
+
+.. code-block:: none
+
+ CREATE KEYSPACE mykeyspace WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} AND durable_writes = true;
+ use mykeyspace ;
+ CREATE TABLE events ( id text, created_at date, content text, PRIMARY KEY (id, created_at) );
+
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-11-19', 'SuperM');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-11-15', 'Billy Joel');
+ INSERT into events (id, created_at, content) VALUES ('game', '2019-11-03', 'Knicks v Sacramento');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-10-31', 'Dead & Company');
+ INSERT into events (id, created_at, content) VALUES ('game', '2019-10-28', 'Knicks v Chicago');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-10-25', 'Billy Joel');
+
+
+ SELECT * from events;
+
+ id | created_at | content
+ ---------+------------+---------------------
+ game | 2019-10-28 | Knicks v Chicago
+ game | 2019-11-03 | Knicks v Sacramento
+ concert | 2019-10-25 | Billy Joel
+ concert | 2019-10-31 | Dead & Company
+ concert | 2019-11-15 | Billy Joel
+ concert | 2019-11-19 | SuperM
+
+ (6 rows)
+
+And you wanted to delete all of the concerts from the month of October using an open-ended range delete. You would run:
+
+.. code-block:: none
+
+ DELETE FROM events WHERE id='concert' AND created_at <= '2019-10-31';
+
+ SELECT * from events;
+
+ id | created_at | content
+ ---------+------------+---------------------
+ game | 2019-10-28 | Knicks v Chicago
+ game | 2019-11-03 | Knicks v Sacramento
+ concert | 2019-11-15 | Billy Joel
+ concert | 2019-11-19 | SuperM
+
+ (4 rows)
+
+.. _batch_statement:
+
+BATCH
+^^^^^
+
+Multiple ``INSERT``, ``UPDATE`` and ``DELETE`` can be executed in a single statement by grouping them through a
+``BATCH`` statement:
+
+.. code-block::
+
+ batch_statement: BEGIN [ UNLOGGED | COUNTER ] BATCH
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : `modification_statement` ( ';' `modification_statement` )*
+ : APPLY BATCH
+ modification_statement: `insert_statement` | `update_statement` | `delete_statement`
+
+For instance:
+
+.. code-block:: cql
+
+ BEGIN BATCH
+ INSERT INTO users (userid, password, name) VALUES ('user2', 'ch@ngem3b', 'second user');
+ UPDATE users SET password = 'ps22dhds' WHERE userid = 'user3';
+ INSERT INTO users (userid, password) VALUES ('user4', 'ch@ngem3c');
+ DELETE name FROM users WHERE userid = 'user1';
+ APPLY BATCH;
+
+The ``BATCH`` statement group multiple modification statements (insertions/updates and deletions) into a single
+statement. It serves several purposes:
+
+- It saves network round-trips between the client and the server (and sometimes between the server coordinator and the
+ replicas) when batching multiple updates.
+- All updates in a ``BATCH`` belonging to a given partition key are performed atomically.
+- By default, all operations in the batch are performed as *logged*, to ensure all mutations eventually complete (or
+ none will). See the notes on :ref:`UNLOGGED batches <unlogged-batches>` for more details.
+
+Note that:
+
+- ``BATCH`` statements may only contain ``UPDATE``, ``INSERT`` and ``DELETE`` statements (not other batches, for instance).
+- Batches are *not* a full analogue for SQL transactions.
+- If a timestamp is not specified for each operation, then all operations will be applied with the same timestamp
+ (either one generated automatically, or the timestamp provided at the batch level). Due to Scylla's conflict
+ resolution procedure in the case of timestamp ties, operations may be applied in an order that is different from the order they are listed in the ``BATCH`` statement. To force a
+ particular operation ordering, you must specify per-operation timestamps.
+- A LOGGED batch to a single partition will be converted to an UNLOGGED batch as an optimization.
+
+``BATCH`` supports the ``TIMESTAMP`` option with the same semantics as the TIMESTAMP parameter in ``UPDATE`` statement.
+For more information on the :token:`update_parameter` refer to the :ref:`UPDATE <update-parameters>` section.
+
+.. _unlogged-batches:
+
+``UNLOGGED`` batches
+~~~~~~~~~~~~~~~~~~~~
+
+By default, Scylla uses a batch log to ensure all operations in a batch eventually complete or none will (note,
+however, that operations are only isolated within a single partition).
+
+There is a performance penalty for batch atomicity when a batch spans multiple partitions. If you do not want to incur
+this penalty, you can tell Scylla to skip the batchlog with the ``UNLOGGED`` option. If the ``UNLOGGED`` option is
+used, a failed batch might leave the patch only partly applied.
+
+``COUNTER`` batches
+~~~~~~~~~~~~~~~~~~~
+
+Use the ``COUNTER`` option for batched counter updates. Unlike other
+updates in Scylla, counter updates are not idempotent.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
diff --git a/docs/getting-started/functions.rst b/docs/getting-started/functions.rst
--- a/docs/getting-started/functions.rst
+++ b/docs/getting-started/functions.rst
@@ -0,0 +1,291 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _cql-functions:
+
+.. Need some intro for UDF and native functions in general and point those to it.
+.. _udfs:
+.. _native-functions:
+
+Functions
+---------
+
+CQL supports two main categories of functions:
+
+- The :ref:`scalar functions <scalar-functions>`, which simply take a number of values and produce an output with it.
+- The :ref:`aggregate functions <aggregate-functions>`, which are used to aggregate multiple rows of results from a
+ ``SELECT`` statement.
+
+.. In both cases, CQL provides a number of native "hard-coded" functions as well as the ability to create new user-defined
+.. functions.
+
+.. .. note:: By default, the use of user-defined functions is disabled by default for security concerns (even when
+.. enabled, the execution of user-defined functions is sandboxed and a "rogue" function should not be allowed to do
+.. evil, but no sandbox is perfect so using user-defined functions is opt-in). See the ``enable_user_defined_functions``
+.. in ``scylla.yaml`` to enable them.
+
+.. A function is identifier by its name:
+
+.. .. code-block::
+
+ function_name: [ `keyspace_name` '.' ] `name`
+
+.. _scalar-functions:
+
+Scalar functions
+^^^^^^^^^^^^^^^^
+
+.. _scalar-native-functions:
+
+Native functions
+~~~~~~~~~~~~~~~~
+
+Cast
+````
+
+Supported starting from Scylla version 2.1
+
+The ``cast`` function can be used to convert one native datatype to another.
+
+The following table describes the conversions supported by the ``cast`` function. Scylla will silently ignore any cast converting a cast datatype into its own datatype.
+
+=============== =======================================================================================================
+ From To
+=============== =======================================================================================================
+ ``ascii`` ``text``, ``varchar``
+ ``bigint`` ``tinyint``, ``smallint``, ``int``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``boolean`` ``text``, ``varchar``
+ ``counter`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``,
+ ``text``, ``varchar``
+ ``date`` ``timestamp``
+ ``decimal`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``varint``, ``text``,
+ ``varchar``
+ ``double`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``float`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``inet`` ``text``, ``varchar``
+ ``int`` ``tinyint``, ``smallint``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``smallint`` ``tinyint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``time`` ``text``, ``varchar``
+ ``timestamp`` ``date``, ``text``, ``varchar``
+ ``timeuuid`` ``timestamp``, ``date``, ``text``, ``varchar``
+ ``tinyint`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``,
+ ``text``, ``varchar``
+ ``uuid`` ``text``, ``varchar``
+ ``varint`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``text``,
+ ``varchar``
+=============== =======================================================================================================
+
+The conversions rely strictly on Java's semantics. For example, the double value 1 will be converted to the text value
+'1.0'. For instance::
+
+ SELECT avg(cast(count as double)) FROM myTable
+
+Token
+`````
+
+The ``token`` function computes a token for a given partition key. The exact signature of the token function
+depends on the table concerned and on the partitioner used by the cluster.
+
+The arguments of the ``token`` depend on the type of the partition key columns that are used. The return type depends on
+the partitioner in use:
+
+- For Murmur3Partitioner, the return type is ``bigint``.
+
+For instance, in a cluster using the default Murmur3Partitioner, if a table is defined by::
+
+ CREATE TABLE users (
+ userid text PRIMARY KEY,
+ username text,
+ )
+
+The ``token`` function accepts single argument of type ``text`` (in that case, the partition key is ``userid``
+(there are no clustering columns, so the partition key is the same as the primary key)), and the return type will be
+``bigint``.
+
+Uuid
+````
+The ``uuid`` function takes no parameters and generates a random type 4 uuid suitable for use in ``INSERT`` or
+``UPDATE`` statements.
+
+.. _timeuuid-functions:
+
+.. Timeuuid functions
+.. ``````````````````
+
+.. ``now``
+.. #######
+
+.. The ``now`` function takes no arguments and generates, on the coordinator node, a new unique timeuuid at the
+.. time the function is invoked. Note that this method is useful for insertion but is largely non-sensical in
+.. ``WHERE`` clauses. For instance, a query of the form::
+
+.. SELECT * FROM myTable WHERE t = now()
+
+.. will never return any result by design, since the value returned by ``now()`` is guaranteed to be unique.
+
+.. ``currentTimeUUID`` is an alias of ``now``.
+
+.. ``minTimeuuid`` and ``maxTimeuuid``
+.. ###################################
+
+.. The ``minTimeuuid`` (resp. ``maxTimeuuid``) function takes a ``timestamp`` value ``t`` (which can be `either a timestamp
+.. or a date string <timestamps>`) and return a *fake* ``timeuuid`` corresponding to the *smallest* (resp. *biggest*)
+.. possible ``timeuuid`` having for timestamp ``t``. So for instance::
+
+.. SELECT * FROM myTable
+.. WHERE t > maxTimeuuid('2013-01-01 00:05+0000')
+.. AND t < minTimeuuid('2013-02-02 10:00+0000')
+
+.. will select all rows where the ``timeuuid`` column ``t`` is strictly older than ``'2013-01-01 00:05+0000'`` but strictly
+.. younger than ``'2013-02-02 10:00+0000'``. Please note that ``t >= maxTimeuuid('2013-01-01 00:05+0000')`` would still
+.. *not* select a ``timeuuid`` generated exactly at '2013-01-01 00:05+0000' and is essentially equivalent to ``t >
+.. maxTimeuuid('2013-01-01 00:05+0000')``.
+
+.. note:: We called the values generated by ``minTimeuuid`` and ``maxTimeuuid`` *fake* UUID because they do no respect
+ the Time-Based UUID generation process specified by the `RFC 4122 <http://www.ietf.org/rfc/rfc4122.txt>`__. In
+ particular, the value returned by these two methods will not be unique. This means you should only use those methods
+ for querying (as in the example above). Inserting the result of those methods is almost certainly *a bad idea*.
+
+Datetime functions
+``````````````````
+
+.. versionadded:: 2.3
+
+Retrieving the current date/time
+################################
+
+The following functions can be used to retrieve the date/time at the time where the function is invoked:
+
+===================== ===============
+Function name Output type
+===================== ===============
+``currentTimestamp`` ``timestamp``
+``currentDate`` ``date``
+``currentTime`` ``time``
+``currentTimeUUID`` ``timeUUID``
+===================== ===============
+
+For example, to retrieve data up to today, run the following query::
+
+ SELECT * FROM myTable WHERE date >= currentDate()
+
+Time conversion functions
+#########################
+
+A number of functions are provided to “convert” a ``timeuuid``, a ``timestamp``, or a ``date`` into another ``native``
+type.
+
+===================== =============== ===================================================================
+Function name Input type Description
+===================== =============== ===================================================================
+``toDate`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``date`` type
+``toDate`` ``timestamp`` Converts the ``timestamp`` argument into a ``date`` type
+``toTimestamp`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``timestamp`` type
+``toTimestamp`` ``date`` Converts the ``date`` argument into a ``timestamp`` type
+``toUnixTimestamp`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``bigInt`` raw value
+``toUnixTimestamp`` ``timestamp`` Converts the ``timestamp`` argument into a ``bigInt`` raw value
+``toUnixTimestamp`` ``date`` Converts the ``date`` argument into a ``bigInt`` raw value
+``dateOf`` ``timeuuid`` Similar to ``toTimestamp(timeuuid)`` (DEPRECATED)
+``unixTimestampOf`` ``timeuuid`` Similar to ``toUnixTimestamp(timeuuid)`` (DEPRECATED)
+===================== =============== ===================================================================
+
+.. Blob conversion functions
+.. `````````````````````````
+.. A number of functions are provided to “convert” the native types into binary data (``blob``). For every
+.. ``<native-type>`` ``type`` supported by CQL (a notable exceptions is ``blob``, for obvious reasons), the function
+.. ``typeAsBlob`` takes a argument of type ``type`` and return it as a ``blob``. Conversely, the function ``blobAsType``
+.. takes a 64-bit ``blob`` argument and convert it to a ``bigint`` value. And so for instance, ``bigintAsBlob(3)`` is
+.. ``0x0000000000000003`` and ``blobAsBigint(0x0000000000000003)`` is ``3``.
+
+
+Blob conversion functions
+`````````````````````````
+A number of functions are provided to “convert” the native types into binary data (``blob``). For every
+``<native-type>`` ``type`` supported by CQL (a notable exception is a ``blob``, for obvious reasons), the function
+``typeAsBlob`` takes an argument of type ``type`` and returns it as a ``blob``. Conversely, the function ``blobAsType``
+takes a 64-bit ``blob`` argument and converts it to a ``bigint`` value. For example, ``bigintAsBlob(3)`` is
+``0x0000000000000003`` and ``blobAsBigint(0x0000000000000003)`` is ``3``.
+
+.. _aggregate-functions:
+
+Aggregate functions
+^^^^^^^^^^^^^^^^^^^
+
+Aggregate functions work on a set of rows. They receive values for each row and return one value for the whole set.
+
+If ``normal`` columns, ``scalar functions``, ``UDT`` fields, ``writetime``, or ``ttl`` are selected together with
+aggregate functions, the values returned for them will be the ones of the first row matching the query.
+
+.. note::
+ The ``LIMIT`` and ``PER PARTITION LIMIT`` used in the ``SELECT`` query will have no effect if the limit is greater
+ than or equal to 1 because they are applied to the output of the aggregate functions (which return one value for
+ the whole set of rows).
+
+
+Native aggregates
+~~~~~~~~~~~~~~~~~
+
+.. _count-function:
+
+Count
+`````
+
+The ``count`` function can be used to count the rows returned by a query. Example::
+
+ SELECT COUNT (*) FROM plays;
+ SELECT COUNT (1) FROM plays;
+
+It also can be used to count the non-null value of a given column::
+
+ SELECT COUNT (scores) FROM plays;
+
+Max and Min
+```````````
+
+The ``max`` and ``min`` functions can be used to compute the maximum and the minimum value returned by a query for a
+given column. For instance::
+
+ SELECT MIN (players), MAX (players) FROM plays WHERE game = 'quake';
+
+Sum
+```
+
+The ``sum`` function can be used, to sum up all the values returned by a query for a given column. For instance::
+
+ SELECT SUM (players) FROM plays;
+
+Avg
+```
+
+The ``avg`` function can be used to compute the average of all the values returned by a query for a given column. For
+instance::
+
+ SELECT AVG (players) FROM plays;
+
+.. _user-defined-aggregates-functions:
+
+.. include:: /rst_include/apache-cql-return-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/images/checkmark-16.png b/docs/getting-started/images/checkmark-16.png
--- a/docs/getting-started/images/checkmark-16.png
+++ b/docs/getting-started/images/checkmark-16.png
null
diff --git a/docs/getting-started/images/x-mark-16.png b/docs/getting-started/images/x-mark-16.png
--- a/docs/getting-started/images/x-mark-16.png
+++ b/docs/getting-started/images/x-mark-16.png
null
diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst
--- a/docs/getting-started/index.rst
+++ b/docs/getting-started/index.rst
@@ -0,0 +1,65 @@
+Getting Started
+===============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ install-scylla/index
+ configure
+ requirements
+ cql
+ cqlsh
+ Scylla Drivers </using-scylla/drivers/index>
+ Migrate to Scylla </using-scylla/migrate-scylla>
+ Integration Solutions </using-scylla/integrations/index>
+ tutorials
+
+.. panel-box::
+ :title: Scylla Requirements
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla System Requirements Guide</getting-started/system-requirements/>`
+ * :doc:`OS Support by Platform and Version</getting-started/os-support/>`
+
+.. panel-box::
+ :title: Install and Configure Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * `Install Scylla (Binary Packages, Docker, or EC2) <https://www.scylladb.com/download/>`_ - Links to the ScyllaDB Download Center
+
+ * :doc:`Configure Scylla</getting-started/system-configuration/>`
+ * :doc:`Run Scylla in a Shared Environment </getting-started/scylla-in-a-shared-environment>`
+ * :doc:`Create a Scylla Cluster - Single Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster/>`
+ * :doc:`Create a Scylla Cluster - Multi Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster-multidc/>`
+
+.. panel-box::
+ :title: Develop Applications for Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Drivers</using-scylla/drivers/index>`
+ * `Get Started Lesson on Scylla University <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/quick-wins-install-and-run-scylla/>`_
+ * :doc:`Apache Cassandra Query Language (CQL) Reference </getting-started/cql/>`
+ * :doc:`CQLSh: the CQL shell</getting-started/cqlsh/>`
+
+.. panel-box::
+ :title: Use Scylla with Third-party Solutions
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Migrate to Scylla </using-scylla/migrate-scylla>` - How to migrate your current database to Scylla
+ * :doc:`Integrate with Scylla </using-scylla/integrations/index>` - Integration solutions with Scylla
+
+
+.. panel-box::
+ :title: Tutorials
+ :id: "getting-started"
+ :class: my-panel
+
+ The tutorials will show you how to use ScyllaDB as a data source for an application.
+
+ * `Build an IoT App with sensor simulator and a REST API <https://care-pet.docs.scylladb.com/>`_ - ScyllaDB Tutorial
+ * `Implement CRUD operations with a TODO App <https://github.com/scylladb/scylla-cloud-getting-started/>`_ - ScyllaDB Cloud Tutorial
diff --git a/docs/getting-started/install-scylla/air-gapped-install.rst b/docs/getting-started/install-scylla/air-gapped-install.rst
--- a/docs/getting-started/install-scylla/air-gapped-install.rst
+++ b/docs/getting-started/install-scylla/air-gapped-install.rst
@@ -0,0 +1,11 @@
+==============================
+Air-gapped Server Installation
+==============================
+
+An air-gapped server is a server without any access to external repositories or connections to any network, including the internet.
+To install Scylla on an air-gapped server, you first need to download the relevant files from a server that is not air-gapped and then and move the files to the air-gapped servers to complete the installation.
+
+There are two ways to install Scylla on an air-gapped server:
+
+- With root privileges (recommended): download the OS specific packages (rpms and debs) and install them with the package manager (dnf and apt). See `Install Scylla on an Air-gapped Server Using the Packages (Option 2) <https://www.scylladb.com/download/?platform=tar>`_.
+- Without root privileges: using the :doc:`Scylla Unified Installer <unified-installer>`.
diff --git a/docs/getting-started/install-scylla/config-commands.rst b/docs/getting-started/install-scylla/config-commands.rst
--- a/docs/getting-started/install-scylla/config-commands.rst
+++ b/docs/getting-started/install-scylla/config-commands.rst
@@ -0,0 +1,69 @@
+==============================
+Scylla Configuration Reference
+==============================
+
+This guide describes the commands that you can use to configure your Scylla clusters.
+The commands are all sent via the command line in a terminal and sudo or root access is not required as long as you have permission to execute in the directory.
+
+.. caution:: You should **only** use configuration settings which are officially supported.
+
+A list of all Scylla commands can be obtained by running
+
+.. code-block:: none
+
+ scylla --help
+
+.. note:: This command displays all Scylla commands as well as Seastar commands. The Seastar commands are listed as Core Options.
+
+For example:
+
+.. code-block:: none
+
+ Scylla version 4.2.3-0.20210104.24346215c2 with build-id 0c8faf8bb8a3a0eda9337aad98ed3a6d814a4fa9 starting ...
+ command used: "scylla --help"
+ parsed command line options: [help]
+ Scylla options:
+ -h [ --help ] show help message
+ --version print version number and exit
+ --options-file arg configuration file (i.e.
+ <SCYLLA_HOME>/conf/scylla.yaml)
+ --memtable-flush-static-shares arg If set to higher than 0, ignore the
+ controller's output and set the
+ memtable shares statically. Do not set
+ this unless you know what you are doing
+ and suspect a problem in the
+ controller. This option will be retired
+ when the controller reaches more
+ maturity
+ --compaction-static-shares arg If set to higher than 0, ignore the
+ controller's output and set the
+ compaction shares statically. Do not
+ set this unless you know what you are
+ doing and suspect a problem in the
+ controller. This option will be retired
+ when the controller reaches more
+ maturity
+
+.. note:: This is an incomplete screenshot. For the complete file, run the command in a terminal.
+
+Scylla Configuration Files and Scylla Commands
+----------------------------------------------
+
+Some Scylla Command Line commands are derived from the `scylla.yaml <https://github.com/scylladb/scylla/blob/master/conf/scylla.yaml>`_ configuration parameters.
+
+For example, in the case of ``cluster_name: 'Test Cluster'`` as seen in the `scylla.yaml <https://github.com/scylladb/scylla/blob/master/conf/scylla.yaml>`_ configuration parameters.
+
+To send this configuration setting with the command line, run:
+
+.. code-block:: none
+
+ scylla --cluster-name 'Test Cluster'
+
+
+As you can see from the example above, the general rule of thumb is:
+
+#. Take a configuration parameter from the scylla.yaml file.
+#. Prepend it with ``scylla --``.
+#. In any place where there is an underscore, replace with a dash.
+#. Run the command in a terminal.
+
diff --git a/docs/getting-started/install-scylla/dev-mod.rst b/docs/getting-started/install-scylla/dev-mod.rst
--- a/docs/getting-started/install-scylla/dev-mod.rst
+++ b/docs/getting-started/install-scylla/dev-mod.rst
@@ -0,0 +1,17 @@
+Scylla Developer Mode
+=====================
+
+If you want to use Scylla in developer mode you need to use the command below (using root privileges)
+
+``sudo scylla_dev_mode_setup --developer-mode 1``
+
+
+This script will write the developer mode setting into ``/etc/scylla.d/dev-mode.conf``
+
+
+
+
+
+
+
+
diff --git a/docs/getting-started/install-scylla/disable-housekeeping.rst b/docs/getting-started/install-scylla/disable-housekeeping.rst
--- a/docs/getting-started/install-scylla/disable-housekeeping.rst
+++ b/docs/getting-started/install-scylla/disable-housekeeping.rst
@@ -0,0 +1,21 @@
+
+=========================================
+Scylla Housekeeping and how to disable it
+=========================================
+
+It is always recommended to run the latest version of Scylla Open Source or Scylla Enterprise.
+The latest stable release version is always available from the `Download Center <https://www.scylladb.com/download/>`_.
+
+When you install Scylla, it installs by default two services: **scylla-housekeeping-restart** and **scylla-housekeeping-daily**. These services check for the latest Scylla version and prompt the user if they are using a version that is older than what is publicly available.
+Information about your Scylla deployment, including the Scylla version currently used, as well as unique user and server identifiers, are collected by a centralized service.
+
+To disable these service, update file ``/etc/scylla.d/housekeeping.cfg`` as follow: ``check-version: False``
+
+See also:
+
+* `Scylla privacy <https://www.scylladb.com/privacy/>`_
+* :doc:`Getting Started </getting-started/index>`
+
+
+
+
diff --git a/docs/getting-started/install-scylla/index.rst b/docs/getting-started/install-scylla/index.rst
--- a/docs/getting-started/install-scylla/index.rst
+++ b/docs/getting-started/install-scylla/index.rst
@@ -0,0 +1,37 @@
+Install Scylla
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ scylla-web-installer
+ unified-installer
+ air-gapped-install
+ rpm-info
+ disable-housekeeping
+ dev-mod
+ config-commands
+
+.. panel-box::
+ :title: Install Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ Keep your versions up-to-date. The two latest versions are supported. Also always install the latest patches for your version.
+
+ * Download and install Scylla Server, Drivers and Tools in `Scylla Download Center <https://www.scylladb.com/download/#server/>`_
+ * :doc:`ScyllaDB Web Installer for Linux <scylla-web-installer>`
+ * :doc:`Scylla Unified Installer (relocatable executable) <unified-installer>`
+ * :doc:`Air-gapped Server Installation <air-gapped-install>`
+ * :doc:`What is in each RPM </getting-started/install-scylla/rpm-info/>`
+ * :doc:`Create a Scylla Cluster - Single Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster/>`
+ * :doc:`Create a Scylla Cluster - Multi Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster-multidc/>`
+ * :doc:`Scylla Developer Mode </getting-started/install-scylla/dev-mod>`
+ * :doc:`Scylla Configuration Command Reference </getting-started/install-scylla/config-commands>`
+ * `Scylla Housekeeping and how to disable it <disable-housekeeping>`_
+
+
+
+
+
diff --git a/docs/getting-started/install-scylla/rpm-info.rst b/docs/getting-started/install-scylla/rpm-info.rst
--- a/docs/getting-started/install-scylla/rpm-info.rst
+++ b/docs/getting-started/install-scylla/rpm-info.rst
@@ -0,0 +1,13 @@
+What is in each RPM
+^^^^^^^^^^^^^^^^^^^
+
+* scylla : Scylla is a highly scalable, eventually consistent, distributed, partitioned row DB. Includes all other packages.
+* scylla-server : The Scylla database server
+* scylla-conf : Scylla configuration package
+* scylla-debuginfo : Debug information for package scylla
+* scylla-jmx : Scylla JMX
+* scylla-kernel-conf : Scylla configuration package for the Linux kernel
+* scylla-machine-image.noarch : Scylla Machine Image
+* scylla-tools.noarch : Scylla Tools, like nodetool, cqlsh, cassandra-stress
+* scylla-tools-core.noarch : Core files for Scylla tools
+* scylla-python3 : A standalone python3 interpreter that can be moved around different Linux machines
diff --git a/docs/getting-started/install-scylla/scylla-web-installer.rst b/docs/getting-started/install-scylla/scylla-web-installer.rst
--- a/docs/getting-started/install-scylla/scylla-web-installer.rst
+++ b/docs/getting-started/install-scylla/scylla-web-installer.rst
@@ -0,0 +1,61 @@
+==================================
+ScyllaDB Web Installer for Linux
+==================================
+
+ScyllaDB Web Installer is a platform-agnostic installation script you can run with ``curl`` to install ScyllaDB on Linux.
+
+See `ScyllaDB Download Center <https://www.scylladb.com/download/#server>`_ for information on manually installing ScyllaDB with platform-specific installation packages.
+
+Prerequisites
+--------------
+
+Ensure that your platform is supported by the ScyllaDB version you want to install.
+See :doc:`OS Support by Platform and Version </getting-started/os-support/>`.
+
+Installing ScyllaDB with Web Installer
+---------------------------------------
+To install ScyllaDB with Web Installer, run:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash
+
+By default, running the script installs the latest official version of ScyllaDB Open Source. You can use the following
+options to install a different version or ScyllaDB Enterprise:
+
+.. list-table::
+ :widths: 20 25 55
+ :header-rows: 1
+
+ * - Option
+ - Acceptable values
+ - Description
+ * - ``--scylla-product``
+ - ``scylla`` | ``scylla-enterprise``
+ - Specifies the ScyllaDB product to install: Open Source (``scylla``) or Enterprise (``scylla-enterprise``) The default is ``scylla``.
+ * - ``--scylla-version``
+ - ``<version number>``
+ - Specifies the ScyllaDB version to install. You can specify the major release (``x.y``) to install the latest patch for that version or a specific patch release (``x.y.x``). The default is the latest official version.
+
+You can run the command with the ``-h`` or ``--help`` flag to print information about the script.
+
+Examples
+---------
+
+Installing ScyllaDB Open Souce 4.6.1:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-version 4.6.1
+
+Installing the latest patch release for ScyllaDB Open Source 4.6:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-version 4.6
+
+Installing ScyllaDB Enterprise 2021.1:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-product scylla-enterprise --scylla-version 2021.1
diff --git a/docs/getting-started/install-scylla/unified-installer.rst b/docs/getting-started/install-scylla/unified-installer.rst
--- a/docs/getting-started/install-scylla/unified-installer.rst
+++ b/docs/getting-started/install-scylla/unified-installer.rst
@@ -0,0 +1,64 @@
+=================================================
+Scylla Unified Installer (relocatable executable)
+=================================================
+
+This document covers how to install, uninstall, and upgrade using the Scylla Unified Installer. The Unified Installer is recommended to be used when you do not have root privileges to the server.
+If you have root privileges, it is recommended to download the OS specific packages (RPMs and DEBs) and install them with the package manager (dnf and apt).
+
+Supported distros
+=================
+
+* CentOS 7 (Only support root offline install)
+* CentOS 8
+* Ubuntu 18.04 (developer-mode is used if NOFILE rlimit is too low)
+* Debian 10
+
+Download and install
+====================
+
+For installation without root privileges, follow the instructions on `Scylla Download Center <https://www.scylladb.com/download/?platform=tar>`_
+
+Upgrade / Downgrade/ Uninstall
+==============================
+
+.. _unified-installed-upgrade:
+
+Upgrade
+-------
+
+The unified package is based on a binary package; it’s not a RPM / DEB packages, so it doesn’t upgrade or downgrade by yum / apt. Currently, only install.sh of scylla supports the upgrade.
+
+Root install:
+
+.. code:: sh
+
+ ./install.sh --upgrade
+
+Nonroot install
+
+.. code:: sh
+
+ ./install.sh --upgrade --nonroot
+
+.. note:: the installation script does not upgrade scylla-jmx and scylla-tools. You will have to do this separately.
+
+Uninstall
+---------
+
+Root uninstall:
+
+.. code:: sh
+
+ sudo ./uninstall.sh
+
+Nonroot uninstall
+
+.. code:: sh
+
+ ./uninstall.sh --nonroot
+
+
+Downgrade
+---------
+
+To downgrade to your original Scylla version, use the Uninstall_ procedure above and then install the original Scylla packages.
diff --git a/docs/getting-started/json.rst b/docs/getting-started/json.rst
--- a/docs/getting-started/json.rst
+++ b/docs/getting-started/json.rst
@@ -0,0 +1,124 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _cql-json:
+
+JSON Support
+------------
+
+.. versionadded:: 2.3
+
+Scylla introduces JSON support to :ref:`SELECT <select-statement>` and :ref:`INSERT <insert-statement>`
+statements. This support does not fundamentally alter the CQL API (for example, the schema is still enforced). It simply
+provides a convenient way to work with JSON documents.
+
+SELECT JSON
+^^^^^^^^^^^
+
+With ``SELECT`` statements, the ``JSON`` keyword can be used to return each row as a single ``JSON`` encoded map. The
+remainder of the ``SELECT`` statement behavior is the same.
+
+The result map keys are the same as the column names in a normal result set. For example, a statement like ``SELECT JSON
+a, ttl(b) FROM ...`` would result in a map with keys ``"a"`` and ``"ttl(b)"``. However, this is one notable exception:
+for symmetry with ``INSERT JSON`` behavior, case-sensitive column names with upper-case letters will be surrounded with
+double-quotes. For example, ``SELECT JSON myColumn FROM ...`` would result in a map key ``"\"myColumn\""`` (note the
+escaped quotes).
+
+The map values will ``JSON``-encoded representations (as described below) of the result set values.
+
+INSERT JSON
+^^^^^^^^^^^
+
+With ``INSERT`` statements, the new ``JSON`` keyword can be used to enable inserting a ``JSON`` encoded map as a single
+row. The format of the ``JSON`` map should generally match that returned by a ``SELECT JSON`` statement on the same
+table. In particular, case-sensitive column names should be surrounded by double-quotes. For example, to insert into a
+table with two columns named "myKey" and "value", you would do the following::
+
+ INSERT INTO mytable JSON '{ "\"myKey\"": 0, "value": 0}'
+
+By default (or if ``DEFAULT NULL`` is explicitly used), a column omitted from the ``JSON`` map will be set to ``NULL``,
+meaning that any pre-existing value for that column will be removed (resulting in a tombstone being created).
+Alternatively, if the ``DEFAULT UNSET`` directive is used after the value, omitted column values will be left unset,
+meaning that pre-existing values for those columns will be preserved.
+
+
+JSON Encoding of Scylla Data Types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Where possible, Scylla will represent and accept data types in their native ``JSON`` representation. Scylla will
+also accept string representations matching the CQL literal format for all single-field types. For example, floats,
+ints, UUIDs, and dates can be represented by CQL literal strings. However, compound types, such as collections, tuples,
+and user-defined types, must be represented by native ``JSON`` collections (maps and lists) or a JSON-encoded string
+representation of the collection.
+
+The following table describes the encodings that Scylla will accept in ``INSERT JSON`` values (and ``fromJson()``
+arguments) as well as the format Scylla will use when returning data for ``SELECT JSON`` statements (and
+``fromJson()``):
+
+=============== ======================== =============== ==============================================================
+ Type Formats accepted Return format Notes
+=============== ======================== =============== ==============================================================
+ ``ascii`` string string Uses JSON's ``\u`` character escape
+ ``bigint`` integer, string integer String must be valid 64 bit integer
+ ``blob`` string string String should be 0x followed by an even number of hex digits
+ ``boolean`` boolean, string boolean String must be "true" or "false"
+ ``date`` string string Date in format ``YYYY-MM-DD``, timezone UTC
+ ``decimal`` integer, float, string float May exceed 32 or 64-bit IEEE-754 floating point precision in
+ client-side decoder
+ ``double`` integer, float, string float String must be valid integer or float
+ ``float`` integer, float, string float String must be valid integer or float
+ ``inet`` string string IPv4 or IPv6 address
+ ``int`` integer, string integer String must be valid 32 bit integer
+ ``list`` list, string list Uses JSON's native list representation
+ ``map`` map, string map Uses JSON's native map representation
+ ``smallint`` integer, string integer String must be valid 16 bit integer
+ ``set`` list, string list Uses JSON's native list representation
+ ``text`` string string Uses JSON's ``\u`` character escape
+ ``time`` string string Time of day in format ``HH-MM-SS[.fffffffff]``
+ ``timestamp`` integer, string string A timestamp. Strings constant allows to input :ref:`timestamps
+ as dates <timestamps>`. Datestamps with format ``YYYY-MM-DD
+ HH:MM:SS.SSS`` are returned.
+ ``timeuuid`` string string Type 1 UUID. See :token:`constant` for the UUID format
+ ``tinyint`` integer, string integer String must be valid 8 bit integer
+ ``tuple`` list, string list Uses JSON's native list representation
+ ``UDT`` map, string map Uses JSON's native map representation with field names as keys
+ ``uuid`` string string See :token:`constant` for the UUID format
+ ``varchar`` string string Uses JSON's ``\u`` character escape
+ ``varint`` integer, string integer Variable length; may overflow 32 or 64 bit integers in
+ client-side decoder
+=============== ======================== =============== ==============================================================
+
+The fromJson() Function
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``fromJson()`` function may be used similarly to ``INSERT JSON``, but for a single column value. It may only be used
+in the ``VALUES`` clause of an ``INSERT`` statement or as one of the column values in an ``UPDATE``, ``DELETE``, or
+``SELECT`` statement. For example, it cannot be used in the selection clause of a ``SELECT`` statement.
+
+The toJson() Function
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``toJson()`` function may be used similarly to ``SELECT JSON``, but for a single column value. It may only be used
+in the selection clause of a ``SELECT`` statement.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/logging.rst b/docs/getting-started/logging.rst
--- a/docs/getting-started/logging.rst
+++ b/docs/getting-started/logging.rst
@@ -0,0 +1,78 @@
+Logging
+=======
+
+Logging with the systemd journal (CentOS, Amazon AMI, Ubuntu, Debian)
+---------------------------------------------------------------------
+On distributions with systemd, Scylla logs are written to the `systemd journal <http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html>`_. You can retrieve log entries with the `journalctl <http://www.freedesktop.org/software/systemd/man/journalctl.html>`_ command.
+
+Listed below are a few useful examples.
+
+* get logs generated by the "scylla" user:
+
+ .. code-block:: shell
+
+ journalctl _UID=`id -u scylla`
+
+* get logs generated by the "scylla" command:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla
+
+* filter only Scylla logs by priority:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -p err..emerg
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -p warning
+
+* filter only Scylla logs by date:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since="2013-3-16 23:59:59"
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since "2015-01-10" --until "2015-01-11 03:00"`
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since yesterday
+
+* filter only Scylla logs since last server boot:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -b
+
+Logging on Ubuntu 14.04
+-----------------------
+On Ubuntu 14.04, Scylla writes its initial boot message into :code:`/var/log/upstart/scylla-server.log`.
+
+After Scylla has started, logs are stored in :code:`/var/log/syslog`. Scylla logs can be filter by creating a :code:`rsyslog` configuration file with the following rule (for example, in :code:`/etc/rsyslog.d/10-scylla.conf`)
+
+.. code-block:: shell
+
+ :syslogtag, startswith, "scylla" /var/log/scylla/scylla.log
+ & ~
+
+And then creating the log file with the correct permissions and restarting the service:
+
+.. code-block:: shell
+
+ install -o syslog -g adm -m 0640 /dev/null /var/log/scylla/scylla.log
+ service rsyslog restart
+
+This will send Scylla only logs to :code:`/var/log/scylla/scylla.log`
+
+Logging on Docker
+-----------------
+Starting from Scylla 1.3, `Scylla Docker <https://hub.docker.com/r/scylladb/scylla/>`_, you should use :code:`docker logs` command to access Scylla server and JMX proxy logs
+
+
+.. include:: /rst_include/advance-index.rst
+
diff --git a/docs/getting-started/mv.rst b/docs/getting-started/mv.rst
--- a/docs/getting-started/mv.rst
+++ b/docs/getting-started/mv.rst
@@ -0,0 +1,184 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _materialized-views:
+
+Materialized Views
+------------------
+Production ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.x
+
+.. include:: /rst_include/cql-version-index.rst
+
+
+Materialized views names are defined by:
+
+.. code-block:: cql
+
+ view_name: re('[a-zA-Z_0-9]+')
+
+
+.. _create-materialized-view-statement:
+
+CREATE MATERIALIZED VIEW
+........................
+
+You can create a materialized view on a table using a ``CREATE MATERIALIZED VIEW`` statement:
+
+.. code-block:: cql
+
+ create_materialized_view_statement: CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] `view_name` AS
+ : `select_statement`
+ : PRIMARY KEY '(' `primary_key` ')'
+ : WITH `table_options`
+
+For instance::
+
+ CREATE MATERIALIZED VIEW monkeySpecies_by_population AS
+ SELECT * FROM monkeySpecies
+ WHERE population IS NOT NULL AND species IS NOT NULL
+ PRIMARY KEY (population, species)
+ WITH comment='Allow query by population instead of species';
+
+The ``CREATE MATERIALIZED VIEW`` statement creates a new materialized view. Each view is a set of *rows* that
+corresponds to the rows that are present in the underlying, or base table, as specified in the ``SELECT`` statement. A
+materialized view cannot be directly updated, but updates to the base table will cause corresponding updates in the
+view.
+
+Creating a materialized view has three main parts:
+
+- The :ref:`select statement <mv-select>` that restricts the data included in the view.
+- The :ref:`primary key <mv-primary-key>` definition for the view.
+- The :ref:`options <mv-options>` for the view.
+
+Attempting to create an already existing materialized view will return an error unless the ``IF NOT EXISTS`` option is
+used. If it is used, the statement will be a no-op if the materialized view already exists.
+
+.. _mv-select:
+
+MV Select Statement
+...................
+
+The select statement of a materialized view creation defines which of the base table is included in the view. That
+statement is limited in a number of ways:
+
+- The :ref:`selection <selection-clause>` is limited to those that only select columns of the base table. In other
+ words, you can't use any function (aggregate or not), casting, term, etc. Aliases are also not supported. You can,
+ however, use `*` as a shortcut to selecting all columns. Further, :ref:`static columns <static-columns>` cannot be
+ included in a materialized view (which means ``SELECT *`` isn't allowed if the base table has static columns).
+- The ``WHERE`` clause has the following restrictions:
+
+ - It cannot include any :token:`bind_marker`.
+ - The columns that are not part of the *base table* primary key can only be restricted by an ``IS NOT NULL``
+ restriction. No other restriction is allowed.
+ - As the columns that are part of the *view* primary key cannot be null, they must always be at least restricted by a
+ ``IS NOT NULL`` restriction (or any other restriction, but they must have one).
+ - They can also be restricted by relational operations (=, >, <).
+
+- The SELECT statement cannot include **any** of the following:
+
+ - An :ref:`ordering clause <ordering-clause>`
+ - A :ref:`limit <limit-clause>` clause
+ - An :ref:`ALLOW FILTERING <allow-filtering>` clause.
+
+.. _mv-primary-key:
+
+MV Primary Key
+..............
+
+A view must have a primary key, and that primary key must conform to the following restrictions:
+
+- It must contain all the primary key columns of the base table. This ensures that every row in the view corresponds to
+ exactly one row of the base table.
+- It can only contain a single column that is not a primary key column in the base table.
+
+So, for instance, give the following base table definition::
+
+ CREATE TABLE t (
+ k int,
+ c1 int,
+ c2 int,
+ v1 int,
+ v2 int,
+ PRIMARY KEY (k, c1, c2)
+ );
+
+then the following view definitions are allowed::
+
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (c1, k, c2);
+
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE v1 IS NOT NULL AND k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (v1, k, c1, c2);
+
+but the following ones are **not** allowed::
+
+ // Error: cannot include both v1 and v2 in the primary key as both are not in the base table primary key
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL AND v1 IS NOT NULL
+ PRIMARY KEY (v1, v2, k, c1, c2)
+
+ // Error: must include k in the primary as it's a base table primary key column
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (c1, c2)
+
+
+.. _mv-options:
+
+MV Options
+..........
+
+A materialized view is internally implemented by a table, and as such, creating a MV allows the :ref:`same options than
+creating a table <create-table-options>`.
+
+
+.. _alter-materialized-view-statement:
+
+ALTER MATERIALIZED VIEW
+.......................
+
+After creation, you can alter the options of a materialized view using the ``ALTER MATERIALIZED VIEW`` statement:
+
+.. code-block::
+
+ alter_materialized_view_statement: ALTER MATERIALIZED VIEW `view_name` WITH `table_options`
+
+The options that can be updated with an ALTER statement are the same as those used with a CREATE statement (see :ref:`Create table options <create-table-options>`).
+
+.. _drop-materialized-view-statement:
+
+DROP MATERIALIZED VIEW
+......................
+
+Dropping a materialized view users the ``DROP MATERIALIZED VIEW`` statement:
+
+.. code-block::
+
+ drop_materialized_view_statement: DROP MATERIALIZED VIEW [ IF EXISTS ] `view_name`;
+
+If the materialized view does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case
+the operation is a no-op.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/non-reserved-keywords.rst b/docs/getting-started/non-reserved-keywords.rst
--- a/docs/getting-started/non-reserved-keywords.rst
+++ b/docs/getting-started/non-reserved-keywords.rst
@@ -0,0 +1,77 @@
+Non-Reserved CQL Keywords
+=========================
+
+CQL distinguishes between reserved and non-reserved keywords.
+
+Non-reserved keywords only have meaning in their particular area of context and can be used as an identifier. The following keywords are non-reserved:
+
+* AGGREGATE
+* ALL
+* AS
+* ASCII
+* BIGINT
+* BLOB
+* BOOLEAN
+* CALLED
+* CLUSTERING
+* COMPACT
+* CONTAINS
+* COUNT
+* COUNTER
+* CUSTOM
+* DATE
+* DECIMAL
+* DISTINCT
+* DOUBLE
+* EXISTS
+* FILTERING
+* FINALFUNC
+* FLOAT
+* FROZEN
+* FUNCTION
+* FUNCTIONS
+* INET
+* INITCOND
+* INPUT
+* INT
+* JSON
+* KEY
+* KEYS
+* KEYSPACES
+* LANGUAGE
+* LIST
+* LOGIN
+* MAP
+* NOLOGIN
+* NOSUPERUSER
+* OPTIONS
+* PASSWORD
+* PERMISSION
+* PERMISSIONS
+* RETURNS
+* ROLE
+* ROLES
+* SFUNC
+* SMALLINT
+* STATIC
+* STORAGE
+* STYPE
+* SUPERUSER
+* TEXT
+* TIME
+* TIMESTAMP
+* TIMEUUID
+* TINYINT
+* TRIGGER
+* TTL
+* TUPLE
+* TYPE
+* USER
+* USERS
+* UUID
+* VALUES
+* VARCHAR
+* VARINT
+* WRITETIME
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/os-support.rst b/docs/getting-started/os-support.rst
--- a/docs/getting-started/os-support.rst
+++ b/docs/getting-started/os-support.rst
@@ -0,0 +1,81 @@
+OS Support by Platform and Version
+==================================
+
+The following matrix shows which Operating Systems, Platforms, and Containers / Instance Engines are supported with which versions of Scylla.
+
+Scylla requires a fix to the XFS append introduced in kernel 3.15 (back-ported to 3.10 in RHEL/CentOS).
+Scylla will not run with earlier kernel versions. Details in `Scylla issue 885 <https://github.com/scylladb/scylla/issues/885>`_.
+
+.. note::
+
+ Scylla Open Source supports x86_64 for all versions and aarch64 starting from Scylla 4.6 and nightly build. In particular, aarch64 support includes AWS EC2 Graviton.
+
+ For Scylla Open Source **4.5** and later, the recommended OS and Scylla AMI/IMage OS is Ubuntu 20.04.4 LTS.
+
+
+Scylla Open Source
+-------------------
+
+.. note:: For Enterprise versions **prior to** 4.6, the recommended OS and Scylla AMI/Image OS is CentOS 7.
+
+ For Scylla Open Source versions **4.6 and later**, the recommended OS and Scylla AMI/Image OS is Ubuntu 20.04.
+
+
+
++--------------------------+----------------------------------+-----------------------------+-------------+
+| Platform | Ubuntu | Debian | Centos/RHEL |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| Scylla Version / Version | 14.04| 16.04| 18.04|20.04 |22.04 | 8 | 9 | 10 | 11 | 7 | 8 |
++==========================+======+======+======+======+======+======+======+=======+=======+======+======+
+| 5.0 | |x| | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.6 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.5 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.4 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.3 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.2 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.1 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.0 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 3.x | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 2.3 | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 2.2 | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+
+
+All releases are available as a Docker container, EC2 AMI, and a GCP image (GCP image from version 4.3).
+
+
+Scylla Enterprise
+-----------------
+
+.. note:: Enterprise versions **prior to** 2021.1, the recommended OS and Scylla AMI/IMage OS is CentOS 7.
+
+ For Enterprise versions **2021.1 and later**, the recommended OS and Scylla AMI/IMage OS is Ubuntu 20.04.4 LTS.
+
+ For Enterprise versions **2021.1 and later**, the recommended OS and Scylla AMI/Image OS is Ubuntu 20.04.
+
++--------------------------+---------------------------+--------------------+------------+
+| Platform | Ubuntu | Debian | Centos/RHEL|
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| Scylla Version / Version | 14 | 16 | 18 | 20 | 8 | 9 | 10 | 7 | 8 |
++==========================+======+======+======+======+======+======+======+======+=====+
+| 2021.1 | |x| | |v| | |v| | |v| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2020.1 | |x| | |v| | |v| | |x| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2019.1 | |x| | |v| | |v| | |x| | |x| | |v| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2018.1 | |v| | |v| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+
+
+All releases are available as a Docker container, EC2 AMI, and a GCP image (GCP image from version 2021.1).
diff --git a/docs/getting-started/requirements.rst b/docs/getting-started/requirements.rst
--- a/docs/getting-started/requirements.rst
+++ b/docs/getting-started/requirements.rst
@@ -0,0 +1,34 @@
+
+===================
+Scylla Requirements
+===================
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ system-requirements
+ os-support
+ scylla-in-a-shared-environment
+
+
+.. raw:: html
+
+
+ <div class="panel callout radius animated">
+ <div class="row">
+ <div class="medium-3 columns">
+ <h5 id="getting-started">Scylla Requirements</h5>
+ </div>
+ <div class="medium-9 columns">
+
+* :doc:`Scylla System Requirements Guide</getting-started/system-requirements/>`
+* :doc:`OS Support by Platform and Version</getting-started/os-support/>`
+* :doc:`Running Scylla in a shared environment </getting-started/scylla-in-a-shared-environment>`
+
+.. raw:: html
+
+ </div>
+ </div>
+ </div>
+
diff --git a/docs/getting-started/reserved-keywords.rst b/docs/getting-started/reserved-keywords.rst
--- a/docs/getting-started/reserved-keywords.rst
+++ b/docs/getting-started/reserved-keywords.rst
@@ -0,0 +1,66 @@
+Reserved CQL Keywords
+=====================
+
+CQL distinguishes between reserved and non-reserved keywords.
+
+Reserved keywords cannot be used as identifiers. They are truly reserved for the language (but one can enclose a reserved keyword by single or double-quotes to use it as an identifier). The following keywords are reserved:
+
+
+* ADD
+* ALLOW
+* ALTER
+* AND
+* APPLY
+* ASC
+* AUTHORIZE
+* BATCH
+* BEGIN
+* BY
+* COLUMNFAMILY
+* CREATE
+* DELETE
+* DESC
+* DESCRIBE
+* DROP
+* ENTRIES
+* EXECUTE
+* FROM
+* FULL
+* GRANT
+* IF
+* IN
+* INDEX
+* INFINITY
+* INSERT
+* INTO
+* KEYSPACE
+* LIMIT
+* MODIFY
+* NAN
+* NORECURSIVE
+* NOT
+* NULL
+* OF
+* ON
+* OR
+* ORDER
+* PRIMARY
+* RENAME
+* REPLACE
+* REVOKE
+* SCHEMA
+* SELECT
+* SET
+* TABLE
+* TO
+* TOKEN
+* TRUNCATE
+* UNLOGGED
+* UPDATE
+* USE
+* USING
+* VIEW
+* WHERE
+* WITH
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/scylla-in-a-shared-environment.rst b/docs/getting-started/scylla-in-a-shared-environment.rst
--- a/docs/getting-started/scylla-in-a-shared-environment.rst
+++ b/docs/getting-started/scylla-in-a-shared-environment.rst
@@ -0,0 +1,85 @@
+
+==============================
+Scylla in a Shared Environment
+==============================
+
+Scylla is designed to utilize all of the resources on the machine. It
+runs on: disk and network bandwidth, RAM, and CPU. This allows you to
+achieve maximum performance with a minimal node count. In development
+and test, however, your nodes might be using a shared machine, which
+Scylla cannot dominate. This article explains how to configure Scylla
+for shared environments. For some production environments, these settings
+may be preferred as well.
+
+Note that a Docker image is a viable and even simpler option - `Scylla
+on dockerhub <https://hub.docker.com/r/scylladb/scylla/>`_
+
+
+Memory
+------
+
+The most critical resource that Scylla consumes is memory. By default,
+when Scylla starts up, it inspects the node's hardware configuration and
+claims *all* memory to itself, leaving some reserve for the operating
+system (OS). This is in contrast to most open-source databases that
+leave most memory for the OS, but is similar to most commercial
+databases.
+
+In a shared environment, particularly on a desktop or laptop, gobbling
+up all the machine's memory can reduce the user experience, so Scylla
+allows reducing its memory usage to a given quantity.
+
+On Ubuntu, open a terminal and edit ``/etc/default/scylla-server``, and add ``--memory 2G``
+to restrict Scylla to 2 gigabytes of RAM.
+
+On Red Hat / CentOS, open a terminal and edit ``/etc/sysconfig/scylla-server``, and add
+``--memory 2G`` to restrict Scylla to 2 gigabytes of RAM.
+
+If starting Scylla from the command line, simply append ``--memory 2G``
+to your command line.
+
+CPU
+---
+
+By default, Scylla will utilize *all* of your processors (in some
+configurations, particularly on Amazon AWS, it may leave a core for the
+operating system). In addition, Scylla will pin its threads to specific
+cores in order to maximize the utilization of the processor on-chip
+caches. On a dedicated node, this allows maximum throughput, but on a
+desktop or laptop, it can cause a sluggish user interface.
+
+Scylla offers two options to restrict its CPU utilization:
+
+- ``--smp N`` restricts Scylla to N logical cores; for example with
+ ``--smp 2`` Scylla will not utilize more than two logical cores
+- ``--overprovisioned`` tells Scylla that the machine it is running on
+ is used by other processes; so Scylla will not pin its threads or
+ memory, and will reduce the amount of polling it does to a minimum.
+
+On Ubuntu edit ``/etc/default/scylla-server``, and add
+``--smp 2 --overprovisioned`` to restrict Scylla to 2 logical cores.
+
+On Red Hat / CentOS edit ``/etc/sysconfig/scylla-server``, and add
+``--smp 2 --overprovisioned`` to restrict Scylla to 2 logical cores.
+
+If starting Scylla from the command line, simply append
+``--smp 2 --overprovisioned`` to your command line.
+
+Other Restrictions
+------------------
+
+When starting up, Scylla will check the hardware and operating system
+configuration to verify that it is compatible with Scylla's performance requirements. See `developer mode`_ for more instructions.
+
+.. _`developer mode`: /getting-started/install-scylla/dev_mod/
+
+
+Summary
+-------
+
+Scylla comes out of the box ready for production use with maximum
+performance but may need to be tuned for development or test uses. This
+tuning is simple to apply and results in a Scylla server that can
+coexist with other processes or a GUI on the system.
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/secondary-indexes.rst b/docs/getting-started/secondary-indexes.rst
--- a/docs/getting-started/secondary-indexes.rst
+++ b/docs/getting-started/secondary-indexes.rst
@@ -0,0 +1,122 @@
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _secondary-indexes:
+
+Global Secondary Indexes
+------------------------
+
+Global Secondary Indexes is production ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.x
+
+
+CQL supports creating secondary indexes on tables, allowing queries on the table to use those indexes. A secondary index
+is identified by a name defined by:
+
+.. code-block::
+
+ index_name: re('[a-zA-Z_0-9]+')
+
+
+
+.. _create-index-statement:
+
+CREATE INDEX
+^^^^^^^^^^^^
+
+Creating a secondary index on a table uses the ``CREATE INDEX`` statement:
+
+.. code-block::
+
+ create_index_statement: CREATE INDEX [ `index_name` ]
+ : ON `table_name` '(' `index_identifier` ')'
+ : [ USING `string` [ WITH OPTIONS = `map_literal` ] ]
+ index_identifier: `column_name`
+ :| ( FULL ) '(' `column_name` ')'
+
+For instance::
+
+ CREATE INDEX userIndex ON NerdMovies (user);
+ CREATE INDEX ON Mutants (abilityId);
+
+The ``CREATE INDEX`` statement is used to create a new (automatic) secondary index for a given (existing) column in a
+given table. A name for the index itself can be specified before the ``ON`` keyword, if desired. If data already exists
+for the column, it will be indexed asynchronously. After the index is created, new data for the column is indexed
+automatically at insertion time.
+
+Local Secondary Index
+^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: Scylla 3.1
+
+:doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes>` is an enhancement of :doc:`Global Secondary Indexes </using-scylla/secondary-indexes>`, which allows Scylla to optimize the use case in which the partition key of the base table is also the partition key of the index. Local Secondary Index syntax is the same as above, with extra parentheses on the partition key.
+
+.. code-block::
+
+ index_identifier: `column_name`
+ :| ( PK ) | KEYS | VALUES | FULL ) '(' `column_name` ')'
+
+Example:
+
+.. code-block:: cql
+
+ CREATE TABLE menus (location text, name text, price float, dish_type text, PRIMARY KEY(location, name));
+ CREATE INDEX ON menus((location),dish_type);
+
+More on :doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes>`
+
+.. Attempting to create an already existing index will return an error unless the ``IF NOT EXISTS`` option is used. If it
+.. is used, the statement will be a no-op if the index already exists.
+
+.. Indexes on Map Keys (supported in Scylla 2.2)
+.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. When creating an index on a :ref:`maps <maps>`, you may index either the keys or the values. If the column identifier is
+.. placed within the ``keys()`` function, the index will be on the map keys, allowing you to use ``CONTAINS KEY`` in
+.. ``WHERE`` clauses. Otherwise, the index will be on the map values.
+
+.. _drop-index-statement:
+
+DROP INDEX
+^^^^^^^^^^
+
+Dropping a secondary index uses the ``DROP INDEX`` statement:
+
+.. code-block::
+
+ drop_index_statement: DROP INDEX [ IF EXISTS ] `index_name`
+
+The ``DROP INDEX`` statement is used to drop an existing secondary index. The argument of the statement is the index
+name, which may optionally specify the keyspace of the index.
+
+.. If the index does not exists, the statement will return an error, unless ``IF EXISTS`` is used in which case the
+.. operation is a no-op.
+
+Additional Information
+----------------------
+
+* :doc:`Global Secondary Indexes </using-scylla/secondary-indexes/>`
+* :doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes/>`
+
+The following courses are available from Scylla University:
+
+* `Materialized Views and Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/>`_
+* `Global Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/topic/global-secondary-indexes/>`_
+* `Local Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/topic/local-secondary-indexes-and-combining-both-types-of-indexes/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/system-configuration.rst b/docs/getting-started/system-configuration.rst
--- a/docs/getting-started/system-configuration.rst
+++ b/docs/getting-started/system-configuration.rst
@@ -0,0 +1,3 @@
+
+
+.. include:: /getting-started/_common/system-configuration-index.rst
diff --git a/docs/getting-started/system-requirements.rst b/docs/getting-started/system-requirements.rst
--- a/docs/getting-started/system-requirements.rst
+++ b/docs/getting-started/system-requirements.rst
@@ -0,0 +1,384 @@
+===================
+System Requirements
+===================
+
+.. _system-requirements-supported-platforms:
+
+Supported Platforms
+===================
+
+Scylla runs on 64-bit Linux. Here, you can find which :doc:`operating systems, distros, and versions </getting-started/os-support>` are supported.
+
+.. _system-requirements-hardware:
+
+Hardware Requirements
+=====================
+
+It’s recommended to have a balanced setup. If there are only 4-8 :term:`Logical Cores <Logical Core (lcore)>`, large disks or 10Gbps networking may not be needed.
+This works in the opposite direction as well.
+Scylla can be used in many types of installation environments.
+
+To see which system would best suit your workload requirements, use the `Scylla Sizing Calculator <https://price-calc.gh.scylladb.com/>`_ to customize Scylla for your usage.
+
+
+
+Core Requirements
+-----------------
+Scylla tries to maximize the resource usage of all system components. The shard-per-core approach allows linear scale-up with the number of cores. As you have more cores, it makes sense to balance the other resources, from memory to network.
+
+CPU
+^^^
+Scylla requires modern Intel CPUs that support the SSE4.2 instruction set and will not boot without it.
+
+The following CPUs are supported by Scylla:
+
+* Intel core: Westmere or later (2010)
+* Intel atom: Goldmont or later (2016)
+* AMD low power: Jaguar or later (2013)
+* AMD standard: Bulldozer or later (2011)
+
+
+In terms of the number of cores, any number will work since Scylla scales up with the number of cores.
+A practical approach is to use a large number of cores as long as the hardware price remains reasonable.
+Between 20-60 logical cores (including hyperthreading) is a recommended number. However, any number will fit.
+When using virtual machines, containers, or the public cloud, remember that each virtual CPU is mapped to a single logical core, or thread.
+Allow Scylla to run independently without any additional CPU intensive tasks on the same server/cores as Scylla.
+
+.. _system-requirements-memory:
+
+Memory Requirements
+-------------------
+The more memory available, the better Scylla performs, as Scylla uses all of the available memory for caching. The wider the rows are in the schema, the more memory will be required. 64 GB-256 GB is the recommended range for a medium to high workload. Memory requirements are calculated based on the number of :abbr:`lcores (logical cores)` you are using in your system.
+
+* Recommended size: 16 GB or 2GB per lcore (whichever is higher)
+* Maximum: 1 TiB per lcore, up to 256 lcores
+* Minimum:
+
+ - For test environments: 1 GB or 256 MiB per lcore (whichever is higher)
+ - For production environments: 4 GB or 0.5 GB per lcore (whichever is higher)
+
+.. _system-requirements-disk:
+
+Disk Requirements
+-----------------
+
+SSD
+^^^
+We highly recommend SSD and local disks. Scylla is built for a large volume of data and large storage per node.
+You can use up to 100:1 Disk/RAM ratio, with 30:1 Disk/RAM ratio as a good rule of thumb; for example, 30 TB of storage requires 1 TB of RAM.
+We recommend a RAID-0 setup and a replication factor of 3 within the local datacenter (RF=3) when there are multiple drives.
+
+HDD
+^^^
+HDDs are supported but may become a bottleneck. Some workloads may work with HDDs, especially if they play nice and minimize random seeks. An example of an HDD-friendly workload is a write-mostly (98% writes) workload, with minimal random reads. If you use HDDs, try to allocate a separate disk for the commit log (not needed with SSDs).
+
+Disk Space
+^^^^^^^^^^
+Scylla is flushing memtables to SSTable data files for persistent storage. SSTables are periodically compacted to improve performance by merging and rewriting data and discarding the old one. Depending on compaction strategy, disk space utilization temporarily increases during compaction. For this reason, you should leave an adequate amount of free disk space available on a node.
+Use the following table as a guidelines for the minimum disk space requirements based on the compaction strategy:
+
+====================================== =========== ============
+Compaction Strategy Recommended Minimum
+====================================== =========== ============
+Size Tiered Compaction Strategy (STCS) 50% 70%
+-------------------------------------- ----------- ------------
+Leveled Compaction Strategy (LCS) 50% 80%
+-------------------------------------- ----------- ------------
+Time-window Compaction Strategy (TWCS) 50% 70%
+-------------------------------------- ----------- ------------
+Incremental Compaction Strategy (ICS) 70% 80%
+====================================== =========== ============
+
+Use the default ICS (Scylla Enterprise) or STCS (Scylla Open Source) unless you'll have a clear understanding that another strategy is better for your use case. More on :doc:`choosing a Compaction Strategy </architecture/compaction/compaction-strategies>`.
+In order to maintain a high level of service availability, keep 50% to 20% free disk space at all times!
+
+.. _system-requirements-network:
+
+Network Requirements
+====================
+
+A network speed of 10 Gbps or more is recommended, especially for large nodes. To tune the interrupts and their queues, run the Scylla setup scripts.
+
+
+Cloud Instance Recommendations
+===============================
+
+Amazon Web Services (AWS)
+--------------------------------
+
+.. note::
+
+ Some of the ScyllaDB configuration features rely on querying instance metadata.
+ Disabling access to instance metadata will impact using Ec2 Snitches and tuning performance.
+ See `AWS - Configure the instance metadata options <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html>`_ for more information.
+
+
+We highly recommend EC2 **I3** instances—High I/O. This family includes the High Storage Instances that provide very fast SSD-backed instance storage optimized for very high random I/O performance and provide high IOPS at a low cost. We recommend using enhanced networking that exposes the physical network cards to the VM.
+
+i3 instances are designed for I/O intensive workloads and equipped with super-efficient NVMe SSD storage. It can deliver up to 3.3 Million IOPS.
+An i3 instance is great for low latency and high throughput, compared to the i2 instances, the i3 instance provides storage that it's less expensive and denser along with the ability to deliver substantially more IOPS and more network bandwidth per CPU core.
+
+i3 instances
+^^^^^^^^^^^^
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i3.xlarge 4 30.5 0.950 TB
+--------------------------- ----------- ------------ ---------------------
+i3.2xlarge 8 61 1.9 TB
+--------------------------- ----------- ------------ ---------------------
+i3.4xlarge 16 122 3.8 TB
+--------------------------- ----------- ------------ ---------------------
+i3.8xlarge 32 244 7.6 TB
+--------------------------- ----------- ------------ ---------------------
+i3.16xlarge 64 488 15.2 TB
+--------------------------- ----------- ------------ ---------------------
+i3.metal New in version 2.3 72 :sup:`*` 512 8 x 1.9 NVMe SSD
+=========================== =========== ============ =====================
+
+:sup:`*` i3.metal provides 72 logical processors on 36 physical cores
+
+Source: `Amazon EC2 I3 Instances <https://aws.amazon.com/ec2/instance-types/i3/>`_
+
+More on using Scylla with `i3.metal vs i3.16xlarge <https://www.scylladb.com/2018/06/21/impact-virtualization-database/>`_
+
+i3en instances
+^^^^^^^^^^^^^^
+i3en instances have up to 4x the networking bandwidth of i3 instances, enabling up to 100 Gbps of sustained network bandwidth.
+
+i3en support is available for Scylla Enterprise 2019.1.1 and higher and Scylla Open Source 3.1 and higher.
+
+
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i3en.large 2 16 1 x 1,250 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.xlarge 4 32 1 x 2,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.2xlarge 8 64 2 x 2,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.3xlarge 12 96 1 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.6xlarge 24 192 2 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.12xlarge 48 384 4 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.24xlarge 96 768 8 x 7,500 GB
+=========================== =========== ============ =====================
+
+All i3en instances have the following specs:
+
+* 3.1 GHz all-core turbo Intel® Xeon® Scalable (Skylake) processors
+* Intel AVX†, Intel AVX2†, Intel AVX-512†, Intel Turbo
+* EBS Optimized
+* Enhanced Networking
+
+See `Amazon EC2 I3en Instances <https://aws.amazon.com/ec2/instance-types/i3en/>`_ for details.
+
+
+i4i instances
+^^^^^^^^^^^^^^
+i4i support is available for ScyllaDB Open Source 5.0 and later and ScyllaDB Enterprise 2021.1.10 and later.
+
+
+
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i4i.large 2 16 1 x 468 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.xlarge 4 32 1 x 937 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.2xlarge 8 64 1 x 1,875 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.4xlarge 16 128 1 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.8xlarge 32 256 2 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.16xlarge 64 512 4 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.32xlarge 128 1,024 8 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.metal 128 1,024 8 x 3,750 GB
+=========================== =========== ============ =====================
+
+All i41 instances have the following specs:
+
+* 3.5 GHz all-core turbo Intel® Xeon® Scalable (Ice Lake) processors
+* 40 Gbps bandwidth to EBS in the largest size and up to 10 Gbps in the four smallest sizes (twice that of i3 instances. Up to 75 Gbps networking bandwidth (three times more than I3 instances).
+* AWS Nitro SSD storage
+
+
+See `Amazon EC2 I4i Instances <https://aws.amazon.com/ec2/instance-types/i4i/>`_ for specification details.
+
+See `ScyllaDB on the New AWS EC2 I4i Instances: Twice the Throughput & Lower Latency <https://www.scylladb.com/2022/05/09/scylladb-on-the-new-aws-ec2-i4i-instances-twice-the-throughput-lower-latency/>`_ to
+learn more about using ScyllaDB with i4i instances.
+
+
+Google Compute Engine (GCE)
+-----------------------------------
+
+Pick a zone where Haswell CPUs are found. Local SSD performance offers, according to Google, less than 1 ms of latency and up to 680,000 read IOPS and 360,000 write IOPS.
+Image with NVMe disk interface is recommended, CentOS 7 for Scylla Enterprise 2020.1 and older, and Ubuntu 20 for 2021.1 and later.
+(`More info <https://cloud.google.com/compute/docs/disks/local-ssd>`_)
+
+Recommended instances types are `n1-highmem <https://cloud.google.com/compute/docs/general-purpose-machines#n1_machines>`_ and `n2-highmem <https://cloud.google.com/compute/docs/general-purpose-machines#n2_machines>`_
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage (GB)
+ * - n1-highmem-2
+ - 2
+ - 13
+ - 375
+ * - n1-highmem-4
+ - 4
+ - 26
+ - 750
+ * - n1-highmem-8
+ - 8
+ - 52
+ - 1,500
+ * - n1-highmem-16
+ - 16
+ - 104
+ - 3,000
+ * - n1-highmem-32
+ - 32
+ - 208
+ - 6,000
+ * - n1-highmem-64
+ - 64
+ - 416
+ - 9,000
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage (GB)
+ * - n2-highmem-2
+ - 2
+ - 16
+ - 375
+ * - n2-highmem-4
+ - 4
+ - 32
+ - 750
+ * - n2-highmem-8
+ - 8
+ - 64
+ - 1500
+ * - n2-highmem-16
+ - 16
+ - 128
+ - 3,000
+ * - n2-highmem-32
+ - 32
+ - 256
+ - 6,000
+ * - n2-highmem-48
+ - 48
+ - 384
+ - 9,000
+ * - n2-highmem-64
+ - 64
+ - 512
+ - 9,000
+ * - n2-highmem-80
+ - 80
+ - 640
+ - 9,000
+
+
+Storage: each instance can support maximum of 24 local SSD of 375 GB partitions each for a total of `9 TB per instance <https://cloud.google.com/compute/docs/disks>`_
+
+.. _system-requirements-azure:
+
+Microsoft Azure
+---------------
+
+The `Lsv2-series <https://azure.microsoft.com/en-us/blog/announcing-the-general-availability-of-lsv2-series-azure-virtual-machines/>`_ features high throughput, low latency, and directly mapped local NVMe storage. The Lsv2 VMs run on the AMD EPYCTM 7551 processor with an all-core boost of 2.55GHz.
+
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage
+ * - L8s_v2
+ - 8
+ - 64
+ - 1 x 1.92 TB
+ * - L16s_v2
+ - 16
+ - 128
+ - 2 x 1.92 TB
+ * - L32s_v2
+ - 32
+ - 256
+ - 4 x 1.92 TB
+ * - L48s_v2
+ - 48
+ - 384
+ - 6 x 1.92 TB
+ * - L64s_v2
+ - 64
+ - 512
+ - 8 x 1.92 TB
+ * - L80s_v2
+ - 80
+ - 640
+ - 10 x 1.92 TB
+
+More on Azure Lsv2 instances `here <https://azure.microsoft.com/en-us/blog/announcing-the-general-availability-of-lsv2-series-azure-virtual-machines/>`_
+
+Oracle Cloud Infrastructure (OCI)
+----------------------------------------
+
+An OCPU is defined as the CPU capacity equivalent of one physical core of an Intel Xeon processor with hyperthreading enabled.
+For Intel Xeon processors, each OCPU corresponds to two hardware execution threads, known as vCPUs.
+
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - OCPU
+ - Mem (GB)
+ - Storage
+ * - VM.DenseIO2.8
+ - 8
+ - 120
+ - 6.4 TB
+ * - VM.DenseIO2.16
+ - 16
+ - 240
+ - 12.8 TB
+ * - VM.DenseIO2.24
+ - 24
+ - 320
+ - 25.6 TB
+ * - BM.DenseIO2.52
+ - 52
+ - 768
+ - 51.2 TB
+ * - BM.HPC2.36
+ - 36
+ - 384
+ - 6.7 TB
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/time-to-live.rst b/docs/getting-started/time-to-live.rst
--- a/docs/getting-started/time-to-live.rst
+++ b/docs/getting-started/time-to-live.rst
@@ -0,0 +1,108 @@
+
+
+.. highlight:: cql
+
+.. _time-to-live:
+
+Expiring Data with Time to Live (TTL)
+-------------------------------------
+
+Scylla (as well as Apache Cassandra) provides the functionality to automatically delete expired data according to the Time to Live (or TTL) value.
+TTL is measured in seconds. If the field is not updated within the TTL it is deleted.
+The TTL can be set when defining a Table (CREATE), or when using the INSERT and UPDATE queries.
+The expiration works at the individual column level, which provides a lot of flexibility.
+By default, the TTL value is null, which means that the data will not expire.
+
+.. note::
+
+ The expiration time is always calculated as *now() on the Coordinator + TTL* where, *now()* is the wall clock during the corresponding write operation.
+ In particular, it means that a value given via USING TIMESTAMP is **not** taken into an account for an expiration calculation.
+
+TTL using UPDATE and INSERT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To set the TTL value using the UPDATE query use the following command:
+
+.. code-block:: cql
+
+ UPDATE heartrate USING TTL 600 SET heart_rate =
+ 110 WHERE pet_chip_id = 123e4567-e89b-12d3-a456-426655440b23;
+
+In this case, the TTL for the heart_rate column is set 10 minutes (600 seconds).
+
+To check the TTL, use the ``TTL()`` function:
+
+.. code-block:: cql
+
+ SELECT name, heart_rate, TTL(heart_rate)
+ FROM heartrate WHERE pet_chip_id = 123e4567-e89b-12d3-a456-426655440b23;
+
+The TTL has a value that is lower than 600 as a few seconds passed between setting the TTL and the SELECT query.
+If you wait 10 minutes and run this command again, you will get a null value for the heart_rate.
+
+It’s also possible to set the TTL when performing an INSERT. To do this use:
+
+.. code-block:: cql
+
+ INSERT INTO heartrate(pet_chip_id, name, heart_rate) VALUES (c63e71f0-936e-11ea-bb37-0242ac130002, 'Rocky', 87) USING TTL 30;
+
+In this case, a TTL of 30 seconds is set.
+
+
+TTL for a Table
+^^^^^^^^^^^^^^^
+Use the CREATE TABLE or ALTER TABLE commands and set the default_time_to_live value:
+
+.. code-block:: cql
+
+ CREATE TABLE heartrate_ttl (
+ pet_chip_id uuid,
+ name text,
+ heart_rate int,
+ PRIMARY KEY (pet_chip_id))
+ WITH default_time_to_live = 600;
+
+Here a TTL of 10 minutes is applied to all rows, however, keep in mind that TTL is stored on a per column level for non-primary key columns.
+
+It’s also possible to change the default_time_to_live on an existing table using the ALTER command:
+
+.. code-block:: cql
+
+ ALTER TABLE heartrate_ttl WITH default_time_to_live = 3600;
+
+TTL with LWT
+.............
+
+.. include:: /rst_include/note-ttl-lwt.rst
+
+Refer to :doc:`LWT </using-scylla/lwt/>` for more information.
+
+The ``gc_grace_seconds`` parameter is defined :ref:`here <create-table-general-options>`.
+
+
+
+TTL for a Collection
+^^^^^^^^^^^^^^^^^^^^
+
+You can set the TTL on a per element basis for collections. An example of how to do this, is shown in the :ref:`Maps <maps>` CQL Reference.
+
+Notes
+^^^^^
+* Notice that setting the TTL on a column using UPDATE or INSERT overrides the default_time_to_live set at the Table level.
+* The TTL is determined by the coordinator node. When using TTL, make sure that all the nodes in the cluster have synchronized clocks.
+* When using TTL for a table, consider using the TWCS compaction strategy.
+* Scylla defines TTL on a per column basis, for non-primary key columns. It’s impossible to set the TTL for the entire row after an initial insert; instead, you can reinsert the row (which is actually an upsert).
+* TTL can not be defined for counter columns.
+* To remove the TTL, set it to 0.
+
+
+
+Additional Information
+----------------------
+
+To learn more about TTL, and see a hands-on example, check out `this lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`_ on Scylla University.
+
+* :doc:`Apache Cassandra Query Language </getting-started/cql/>`
+* :doc:`KB Article:How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds/>`
+* :doc:`KB Article:Time to Live (TTL) and Compaction </kb/ttl-facts/>`
+* :ref:`CQL Reference: Table Options <create-table-general-options>`
diff --git a/docs/getting-started/tutorials.rst b/docs/getting-started/tutorials.rst
--- a/docs/getting-started/tutorials.rst
+++ b/docs/getting-started/tutorials.rst
@@ -0,0 +1,16 @@
+============
+Tutorials
+============
+
+The tutorials will show you how to use ScyllaDB as a data source for an application.
+
+
+ScyllaDB Tutorial
+===================
+
+`Build an IoT App with sensor simulator and a REST API <https://care-pet.docs.scylladb.com/>`_
+
+ScyllaDB Cloud Tutorial
+=======================
+
+`Implement CRUD operations with a TODO App <https://github.com/scylladb/scylla-cloud-getting-started/>`_
diff --git a/docs/getting-started/types.rst b/docs/getting-started/types.rst
--- a/docs/getting-started/types.rst
+++ b/docs/getting-started/types.rst
@@ -0,0 +1,679 @@
+Data Types
+----------
+.. _data-types:
+
+
+.. highlight:: cql
+
+.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+
+
+
+.. include:: /rst_include/cql-version-index.rst
+
+
+
+CQL is a typed language and supports a rich set of data types, including :ref:`native types <native-types>` and
+:ref:`collection types <collections>`.
+
+.. code-block::
+
+ cql_type: `native_type` | `collection_type` | `user_defined_type` | `tuple_type`
+
+
+
+Working with Bytes
+^^^^^^^^^^^^^^^^^^
+
+Bytes can be input with:
+
+* a hexadecimal literal.
+* one of the ``typeAsBlob()`` cql functions. There is such a function for each native type.
+
+For example:
+
+.. code-block:: cql
+
+
+ INSERT INTO blobstore (id, data) VALUES (4375645, 0xabf7971528cfae76e00000008bacdf);
+ INSERT INTO blobstore (id, data) VALUES (4375645, intAsBlob(33));
+
+.. _native-types:
+
+Native Types
+^^^^^^^^^^^^
+
+The native types supported by CQL are:
+
+.. code-block:: cql
+
+ native_type: ASCII
+ : | BIGINT
+ : | BLOB
+ : | BOOLEAN
+ : | COUNTER
+ : | DATE
+ : | DECIMAL
+ : | DOUBLE
+ : | DURATION
+ : | FLOAT
+ : | INET
+ : | INT
+ : | SMALLINT
+ : | TEXT
+ : | TIME
+ : | TIMESTAMP
+ : | TIMEUUID
+ : | TINYINT
+ : | UUID
+ : | VARCHAR
+ : | VARINT
+
+The following table gives additional information on the native data types and which kind of :ref:`constants
+<constants>` each type supports:
+
+======================= ===================== ========================================================================================================
+ type constants supported description
+======================= ===================== ========================================================================================================
+ ``ascii`` :token:`string` ASCII character string
+ ``bigint`` :token:`integer` 64-bit signed long
+ ``blob`` :token:`blob` Arbitrary bytes (no validation). See `Working with Bytes`_ for details
+ ``boolean`` :token:`boolean` Either ``true`` or ``false``
+ ``counter`` :token:`integer` Counter column (64-bit signed value). See :ref:`counters` for details
+ ``date`` :token:`integer`, A date (with no corresponding time value). See :ref:`dates` below for details
+ :token:`string`
+ ``decimal`` :token:`integer`, Variable-precision decimal
+ :token:`float`
+ ``double`` :token:`integer` 64-bit IEEE-754 floating point
+ :token:`float`
+ ``duration`` :token:`duration`, A duration with nanosecond precision. See :ref:`durations` below for details
+ ``float`` :token:`integer`, 32-bit IEEE-754 floating point
+ :token:`float`
+ ``inet`` :token:`string` An IP address, either IPv4 (4 bytes long) or IPv6 (16 bytes long). Note that
+ there is no ``inet`` constant, IP address should be input as strings
+ ``int`` :token:`integer` 32-bit signed int
+ ``smallint`` :token:`integer` 16-bit signed int
+ ``text | varchar`` :token:`string` UTF8 encoded string
+ ``time`` :token:`integer`, A time (with no corresponding date value) with nanosecond precision. See
+ :token:`string` :ref:`times` below for details
+ ``timestamp`` :token:`integer`, A timestamp (date and time) with millisecond precision. See :ref:`timestamps`
+ :token:`string` below for details
+ ``timeuuid`` :token:`uuid` Version 1 UUID_, generally used as a “conflict-free” timestamp. See `Working with UUIDs`_ for details
+ ``tinyint`` :token:`integer` 8-bit signed int
+ ``uuid`` :token:`uuid` A UUID_ (of any version). See `Working with UUIDs`_ for details
+ ``varint`` :token:`integer` Arbitrary-precision integer
+======================= ===================== ========================================================================================================
+
+.. _counters:
+
+Counters
+~~~~~~~~
+
+The ``counter`` type is used to define *counter columns*. A counter column is a column with a 64-bit signed
+integer value and on which two operations are supported: incrementing and decrementing (see the :ref:`UPDATE statement
+<update-statement>` for syntax). Note that the value of a counter cannot be set: a counter does not exist until first
+incremented/decremented, and that first increment/decrement is made as if the prior value was 0.
+
+.. _counter-limitations:
+
+Counters have a number of important limitations:
+
+- They cannot be used for columns part of the ``PRIMARY KEY`` of a table.
+- A table that contains a counter can only contain counters. In other words, either all the columns of a table outside
+ the ``PRIMARY KEY`` have the ``counter`` type, or none of them have it.
+- Counters do not support expiration.
+- The deletion of counters is supported but is only guaranteed to work the first time you delete a counter. In other
+ words, you should not re-update a counter that you have deleted (if you do, proper behavior is not guaranteed).
+- Counter updates are, by nature, **not** `idempotent <https://en.wikipedia.org/wiki/Idempotence>`__. An important
+ consequence is that if a counter update fails unexpectedly (timeout or loss of connection to the coordinator node),
+ the client has no way to know if the update has been applied or not. In particular, replaying the update may or may
+ not lead to an overcount.
+
+.. _timestamps:
+
+Working with timestamps
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Values of the ``timestamp`` type are encoded as 64-bit signed integers representing a number of milliseconds since the
+standard base time known as `the epoch <https://en.wikipedia.org/wiki/Unix_time>`__: January 1st 1970 at 00:00:00 GMT.
+
+Timestamps can be input in CQL either using their value as an :token:`integer`, or using a :token:`string` that
+represents an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ date. For instance, all of the values below are
+valid ``timestamp`` values for Mar 2, 2011, at 04:05:00 AM, GMT:
+
+- ``1299038700000``
+- ``'2011-02-03 04:05+0000'``
+- ``'2011-02-03 04:05:00+0000'``
+- ``'2011-02-03 04:05:00.000+0000'``
+- ``'2011-02-03T04:05+0000'``
+- ``'2011-02-03T04:05:00+0000'``
+- ``'2011-02-03T04:05:00.000+0000'``
+
+The ``+0000`` above is an RFC 822 4-digit time zone specification; ``+0000`` refers to GMT. US Pacific Standard Time is
+``-0800``. The time zone may be omitted if desired (``'2011-02-03 04:05:00'``), and if so, the date will be interpreted
+as being in the time zone under which the coordinating Scylla node is configured. However, there are difficulties
+inherent in relying on the time zone configuration as expected, so it is recommended that the time zone always be
+specified for timestamps when feasible.
+
+The time of day may also be omitted (``'2011-02-03'`` or ``'2011-02-03+0000'``), in which case the time of day will
+default to 00:00:00 in the specified or default time zone. However, if only the date part is relevant, consider using
+the :ref:`date <dates>` type.
+
+.. _dates:
+
+Working with dates
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``date`` type are encoded as 32-bit unsigned integers representing a number of days with “the epoch” at
+the center of the range (2^31). Epoch is January 1st, 1970.
+
+As for :ref:`timestamp <timestamps>`, a date can be input either as an :token:`integer` or using a date
+:token:`string`. In the latter case, the format should be ``yyyy-mm-dd`` (so ``'2011-02-03'``, for instance).
+
+.. _times:
+
+Working with times
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``time`` type are encoded as 64-bit signed integers representing the number of nanoseconds since midnight.
+
+As for :ref:`timestamp <timestamps>`, time can be input either as an :token:`integer` or using a :token:`string`
+representing the time. In the latter case, the format should be ``hh:mm:ss[.fffffffff]`` (where the sub-second precision
+is optional and if provided, can be less than the nanosecond). So, for instance, the following are valid inputs for a
+time:
+
+- ``'08:12:54'``
+- ``'08:12:54.123'``
+- ``'08:12:54.123456'``
+- ``'08:12:54.123456789'``
+
+.. _durations:
+
+Working with durations
+^^^^^^^^^^^^^^^^^^^^^^
+
+Values of the ``duration`` type are encoded as three signed integers of variable lengths. The first integer represents the
+number of months, the second the number of days, and the third the number of nanoseconds. This is due to the fact that
+the number of days in a month can change, and a day can have 23 or 25 hours depending on the daylight saving.
+Internally, the number of months and days is decoded as 32 bits integers, whereas the number of nanoseconds is decoded
+as a 64 bits integer.
+
+A duration can be input as:
+
+#. ``(quantity unit)+`` like ``12h30m`` where the unit can be:
+
+ * ``y``: years (12 months)
+ * ``mo``: months (1 month)
+ * ``w``: weeks (7 days)
+ * ``d``: days (1 day)
+ * ``h``: hours (3,600,000,000,000 nanoseconds)
+ * ``m``: minutes (60,000,000,000 nanoseconds)
+ * ``s``: seconds (1,000,000,000 nanoseconds)
+ * ``ms``: milliseconds (1,000,000 nanoseconds)
+ * ``us`` or ``µs`` : microseconds (1000 nanoseconds)
+ * ``ns``: nanoseconds (1 nanosecond)
+#. ISO 8601 format: ``P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W``
+#. ISO 8601 alternative format: ``P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]``
+
+For example::
+
+ INSERT INTO RiderResults (rider, race, result) VALUES ('Christopher Froome', 'Tour de France', 89h4m48s);
+ INSERT INTO RiderResults (rider, race, result) VALUES ('BARDET Romain', 'Tour de France', PT89H8M53S);
+ INSERT INTO RiderResults (rider, race, result) VALUES ('QUINTANA Nairo', 'Tour de France', P0000-00-00T89:09:09);
+
+.. _duration-limitation:
+
+Duration columns cannot be used in a table's ``PRIMARY KEY``. This limitation is due to the fact that
+durations cannot be ordered. It is effectively not possible to know if ``1mo`` is greater than ``29d`` without a date
+context.
+
+A ``1d`` duration does not equal to a ``24h`` one as the duration type has been created to be able to support daylight
+saving.
+
+Working with UUIDs
+^^^^^^^^^^^^^^^^^^
+
+The values of the UUID type are encoded as 32 hex (base 16) digits,
+in five groups separated by hyphens (-), in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens).
+
+Use an integer literal and not a string. For example ``123e4567-e89b-12d3-a456-426655440000`` and not ``'123e4567-e89b-12d3-a456-426655440000'``.
+
+
+.. _collections:
+
+Collections
+^^^^^^^^^^^
+
+CQL supports 3 kinds of collections: :ref:`maps`, :ref:`sets` and :ref:`lists`. The types of those collections is defined
+by:
+
+.. code-block:: cql
+
+ collection_type: MAP '<' `cql_type` ',' `cql_type` '>'
+ : | SET '<' `cql_type` '>'
+ : | LIST '<' `cql_type` '>'
+
+and their values can be input using collection literals:
+
+.. code-block:: cql
+
+ collection_literal: `map_literal` | `set_literal` | `list_literal`
+
+ map_literal: '{' [ `term` ':' `term` (',' `term` : `term`)* ] '}'
+
+ set_literal: '{' [ `term` (',' `term`)* ] '}'
+
+ list_literal: '[' [ `term` (',' `term`)* ] ']'
+
+Note that neither :token:`bind_marker` nor ``NULL`` are supported inside collection literals.
+
+Noteworthy characteristics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Collections are meant for storing/denormalizing a relatively small amount of data. They work well for things like “the
+phone numbers of a given user”, “labels applied to an email”, etc. But when items are expected to grow unbounded (“all
+messages sent by a user”, “events registered by a sensor”...), then collections are not appropriate, and a specific table
+(with clustering columns) should be used. A collection can be **frozen** or **non-frozen**.
+A non-frozen collection can be modified, i.e., have an element added or removed. A
+frozen collection can only be updated as a whole. By default, a collection is non-frozen.
+To declare a frozen collection, use ``FROZEN`` keyword:
+
+.. code-block:: cql
+
+ frozen_collection_type: FROZEN '<' MAP '<' `cql_type` ',' `cql_type` '>' '>'
+ : | FROZEN '<' SET '<' `cql_type` '>' '>'
+ : | FROZEN '<' LIST '<' `cql_type` '>' '>'
+
+Non-frozen collections have the following noteworthy characteristics and limitations:
+
+- Individual collections are not indexed internally. This means that even to access a single element of a collection,
+ the whole collection has to be read (and reading one is not paged internally).
+- While insertion operations on sets and maps never incur a read-before-write internally, some operations on lists do.
+ Further, some list operations are not idempotent by nature (see the section on :ref:`lists <lists>` below for
+ details), making their retry in case of timeout problematic. It is thus advised to prefer sets over lists when
+ possible.
+
+Please note that while some of those limitations may or may not be removed/improved upon in the future, it is an
+anti-pattern to use a (single) collection to store large amounts of data.
+
+.. _maps:
+
+Maps
+~~~~
+
+A ``map`` is a (sorted) set of key-value pairs, where keys are unique, and the map is sorted by its keys. You can define a map column with::
+
+ CREATE TABLE users (
+ id text PRIMARY KEY,
+ name text,
+ favs map<text, text> // A map of text keys, and text values
+ );
+
+A map column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the map's
+old content, if any::
+
+ INSERT INTO users (id, name, favs)
+ VALUES ('jsmith', 'John Smith', { 'fruit' : 'Apple', 'band' : 'Beatles' });
+
+ UPDATE users SET favs = { 'fruit' : 'Banana' } WHERE id = 'jsmith';
+
+Note that Scylla does not distinguish an empty map from a missing value,
+thus assigning an empty map (``{}``) to a map is the same as deleting it.
+
+Further, maps support:
+
+- Updating or inserting one or more elements::
+
+ UPDATE users SET favs['author'] = 'Ed Poe' WHERE id = 'jsmith';
+ UPDATE users SET favs = favs + { 'movie' : 'Cassablanca', 'band' : 'ZZ Top' } WHERE id = 'jsmith';
+
+- Removing one or more element (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ DELETE favs['author'] FROM users WHERE id = 'jsmith';
+ UPDATE users SET favs = favs - { 'movie', 'band'} WHERE id = 'jsmith';
+
+ Note that for removing multiple elements in a ``map``, you remove from it a ``set`` of keys.
+
+Lastly, TTLs are allowed for both ``INSERT`` and ``UPDATE``, but in both cases, the TTL set only applies to the newly
+inserted/updated elements. In other words::
+
+ UPDATE users USING TTL 10 SET favs['color'] = 'green' WHERE id = 'jsmith';
+
+will only apply the TTL to the ``{ 'color' : 'green' }`` record, the rest of the map remaining unaffected.
+
+.. _sets:
+
+Sets
+~~~~
+
+A ``set`` is a (sorted) collection of unique values. You can define a set column with::
+
+ CREATE TABLE images (
+ name text PRIMARY KEY,
+ owner text,
+ tags set<text> // A set of text values
+ );
+
+A set column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the set's
+old content, if any::
+
+ INSERT INTO images (name, owner, tags)
+ VALUES ('cat.jpg', 'jsmith', { 'pet', 'cute' });
+
+ UPDATE images SET tags = { 'kitten', 'cat', 'lol' } WHERE name = 'cat.jpg';
+
+Note that Scylla does not distinguish an empty set from a missing value,
+thus assigning an empty set (``{}``) to a set is the same as deleting it.
+
+Further, sets support:
+
+- Adding one or multiple elements (as this is a set, inserting an already existing element is a no-op)::
+
+ UPDATE images SET tags = tags + { 'gray', 'cuddly' } WHERE name = 'cat.jpg';
+
+- Removing one or multiple elements (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ UPDATE images SET tags = tags - { 'cat' } WHERE name = 'cat.jpg';
+
+Lastly, as for :ref:`maps <maps>`, TTLs, if used, only apply to the newly inserted values.
+
+.. _lists:
+
+Lists
+~~~~~
+
+.. note:: As mentioned above and further discussed at the end of this section, lists have limitations and specific
+ performance considerations that you should take into account before using them. In general, if you can use a
+ :ref:`set <sets>` instead of a list, always prefer a set.
+
+
+A ``list`` is an ordered list of values (not necessarily unique). You can define a list column with::
+
+ CREATE TABLE plays (
+ id text PRIMARY KEY,
+ game text,
+ players int,
+ scores list<int> // A list of integers
+ );
+
+A list column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the list's
+old content, if any::
+
+ INSERT INTO plays (id, game, players, scores)
+ VALUES ('123-afde', 'quake', 3, [17, 4, 2]);
+
+ UPDATE plays SET scores = [ 3, 9, 4] WHERE id = '123-afde';
+
+Note that Scylla does not distinguish an empty list from a missing value,
+thus assigning an empty list (``[]``) to a list is the same as deleting it.
+
+Further, lists support:
+
+- Appending and prepending values to a list::
+
+ UPDATE plays SET players = 5, scores = scores + [ 14, 21 ] WHERE id = '123-afde';
+ UPDATE plays SET players = 6, scores = [ 3 ] + scores WHERE id = '123-afde';
+
+- Setting the value at a particular position in the list. This implies that the list has a pre-existing element for that
+ position or an error will be thrown that the list is too small::
+
+ UPDATE plays SET scores[1] = 7 WHERE id = '123-afde';
+
+- Removing an element by its position in the list. This implies that the list has a pre-existing element for that position,
+ or an error will be thrown that the list is too small. Further, as the operation removes an element from the list, the
+ list size will be diminished by 1, shifting the position of all the elements following the one deleted::
+
+ DELETE scores[1] FROM plays WHERE id = '123-afde';
+
+- Deleting *all* the occurrences of particular values in the list (if a particular element doesn't occur at all in the
+ list, it is simply ignored, and no error is thrown)::
+
+ UPDATE plays SET scores = scores - [ 12, 21 ] WHERE id = '123-afde';
+
+.. warning:: The append and prepend operations are not idempotent by nature. So, in particular, if one of these operation
+ timeouts, then retrying the operation is not safe, and it may (or may not) lead to appending/prepending the value
+ twice.
+
+.. warning:: Setting and removing an element by position and removing occurrences of particular values incur an internal
+ *read-before-write*. They will thus run more slowly and take more resources than usual updates (with the exclusion
+ of conditional write that have their own cost).
+
+Lastly, as for :ref:`maps <maps>`, TTLs, when used, only apply to the newly inserted values.
+
+.. _udts:
+
+User-Defined Types
+^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 3.2 Scylla Open Source
+
+CQL support the definition of user-defined types (UDT for short). Such a type can be created, modified and removed using
+the :token:`create_type_statement`, :token:`alter_type_statement` and :token:`drop_type_statement` described below. But
+once created, a UDT is simply referred to by its name:
+
+.. code-block::
+
+ user_defined_type: `udt_name`
+ udt_name: [ `keyspace_name` '.' ] `identifier`
+
+
+Creating a UDT
+~~~~~~~~~~~~~~
+
+.. versionchanged:: 3.2 Scylla Open Source
+
+.. note:: If you are using Scylla Open Source 3.1.x (and prior) or Scylla Enterprise (any version), UDTs must be **frozen** - meaning you cannot update individual components of the UDT value. The whole value must be overwritten. Starting with Scylla Open Source 3.2, UDTs that are not in a collection **can be non-frozen**.
+
+Creating a new user-defined type is done using a ``CREATE TYPE`` statement defined by:
+
+.. code-block::
+
+ create_type_statement: CREATE TYPE [ IF NOT EXISTS ] `udt_name`
+ : '(' `field_definition` ( ',' `field_definition` )* ')'
+ field_definition: `identifier` `cql_type`
+
+A UDT has a name (``udt_name``), which is used to declare columns of that type and is a set of named and typed fields. The ``udt_name`` can be any
+type, including collections or other UDTs. UDTs and collections inside collections must always be frozen (no matter which version of Scylla you are using).
+
+For example::
+
+ CREATE TYPE full_name (
+ first text,
+ last text
+ );
+
+
+ CREATE TYPE phone (
+ country_code int,
+ number text,
+ );
+
+ CREATE TYPE address (
+ street text,
+ city text,
+ zip text,
+ phones map<text, frozen<phone>>
+ );
+
+
+ CREATE TABLE superheroes (
+ name frozen<full_name> PRIMARY KEY,
+ home frozen<address>
+ );
+
+.. note::
+
+ - Attempting to create an already existing type will result in an error unless the ``IF NOT EXISTS`` option is used. If it is used, the statement will be a no-op if the type already exists.
+ - A type is intrinsically bound to the keyspace in which it is created and can only be used in that keyspace. At creation, if the type name is prefixed by a keyspace name, it is created in that keyspace. Otherwise, it is created in the current keyspace.
+ - As of Scylla Open Source 3.2, UDTs not inside collections do not have to be frozen, but in all versions prior to Scylla Open Souce 3.2, and in all Scylla Enterprise versions, UDTs **must** be frozen.
+
+
+A non-frozen UDT example with Scylla Open Source 3.2 and higher::
+
+ CREATE TYPE ut (a int, b int);
+ CREATE TABLE cf (a int primary key, b ut);
+
+Same UDT in versions prior::
+
+ CREATE TYPE ut (a int, b int);
+ CREATE TABLE cf (a int primary key, b frozen<ut>);
+
+UDT literals
+~~~~~~~~~~~~
+
+Once a user-defined type has been created, value can be input using a UDT literal:
+
+.. code-block::
+
+ udt_literal: '{' `identifier` ':' `term` ( ',' `identifier` ':' `term` )* '}'
+
+In other words, a UDT literal is like a :ref:`map <maps>` literal but its keys are the names of the fields of the type.
+For instance, one could insert into the table defined in the previous section using::
+
+
+ INSERT INTO superheroes (name, home)
+ VALUES ({first: 'Buffy', last: 'Summers'},
+ {street: '1630 Revello Drive',
+ city: 'Sunnydale',
+ phones: { 'land-line' : { country_code: 1, number: '1234567890'},
+ 'fax' : { country_code: 1, number: '10000000'}}
+ }
+ );
+
+ INSERT INTO superheroes (name, home)
+ VALUES ({first: 'Al', last: 'Bundy'},
+ {street: '9764 Jeopardy Lane',
+ city: 'Chicago'});
+
+To be valid, a UDT literal should only include fields defined by the type it is a literal of, but it can omit some fields
+(in which case those will be ``null``).
+
+
+You can use UDT in a WHERE clause of a SELECT statement as follow::
+
+ SELECT * from superheroes WHERE name={first: 'Al', last: 'Bundy'};
+
+result::
+
+ name | home
+ ------------------------------+--------------------------------------------------------------------------
+ {first: 'Al', last: 'Bundy'} | {street: '9764 Jeopardy Lane', city: 'Chicago', zip: null, phones: null}
+
+
+
+Note that if you provide a subset of the UDT, for example, just the ``first`` name in the example below, **null** will be used for the missing values.
+For example::
+
+ SELECT * from superheroes WHERE name={first: 'Al', last: 'Bundy'};
+
+result::
+
+ name | home
+ ------+------
+
+ (0 rows)
+
+
+Altering a UDT
+~~~~~~~~~~~~~~
+
+An existing user-defined type can be modified using an ``ALTER TYPE`` statement:
+
+.. code-block::
+
+ alter_type_statement: ALTER TYPE `udt_name` `alter_type_modification`
+ alter_type_modification: ADD `field_definition`
+ : | RENAME `identifier` TO `identifier` ( `identifier` TO `identifier` )*
+
+You can:
+
+- Add a new field to the type (``ALTER TYPE address ADD country text``). That new field will be ``null`` for any values
+ of the type created before the addition.
+- Rename the fields of the type (``ALTER TYPE address RENAME zip TO zipcode``).
+
+Dropping a UDT
+~~~~~~~~~~~~~~
+
+You can drop an existing user-defined type using a ``DROP TYPE`` statement:
+
+.. code-block::
+
+ drop_type_statement: DROP TYPE [ IF EXISTS ] `udt_name`
+
+Dropping a type results in the immediate, irreversible removal of that type. However, attempting to drop a type that is
+still in use by another type, table or function will result in an error.
+
+If the type dropped does not exist, an error will be returned unless ``IF EXISTS`` is used, in which case the operation
+is a no-op.
+
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also supports tuples and tuple types (where the elements can be of different types). Functionally, tuples can be
+thought as anonymous UDTs with anonymous fields. Tuple types and tuple literals are defined by:
+
+.. code-block::
+
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always ``frozen<tuple>`` (without the need of the
+`frozen` keyword), and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always provide values for all the components of the tuple type (some of
+those values can be null, but they need to be explicitly declared as so).
+
+.. .. _custom-types:
+
+.. Custom Types
+.. ^^^^^^^^^^^^
+
+.. .. note:: Custom types exists mostly for backward compatiliby purposes and their usage is discouraged. Their usage is
+.. complex, not user friendly and the other provided types, particularly :ref:`user-defined types <udts>`, should almost
+.. always be enough.
+
+.. A custom type is defined by:
+
+.. .. code-block::
+
+.. custom_type: `string`
+
+.. A custom type is a :token:`string` that contains the name of Java class that extends the server side ``AbstractType``
+.. class and that can be loaded by Apache Cassandra (it should thus be in the ``CLASSPATH`` of every node running Cassandra). That
+.. class will define what values are valid for the type and how the time sorts when used for a clustering column. For any
+.. other purpose, a value of a custom type is the same than that of a ``blob``, and can in particular be input using the
+.. :token:`blob` literal syntax.
+
+.. include:: /rst_include/apache-cql-return-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
diff --git a/docs/getting-started/x-mark-16.png b/docs/getting-started/x-mark-16.png
--- a/docs/getting-started/x-mark-16.png
+++ b/docs/getting-started/x-mark-16.png
null
diff --git a/docs/glossary.rst b/docs/glossary.rst
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -0,0 +1,178 @@
+.. _glossary:
+
+=====================
+Glossary
+=====================
+
+.. glossary::
+ :sorted:
+
+ Bootstrap
+ When a new node is added to a cluster, the bootstrap process ensures that the data in the cluster is automatically redistributed to the new node. A new node in this case is an empty node without system tables or data. See :ref:`bootstrap <temporary-fallback-to-stcs>`.
+
+ Anti-entropy
+ A state where data is in order and organized. Scylla has processes in place to make sure that data is antientropic where all replicas contain the most recent data and that data is consistent between replicas. See :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index>`.
+
+ CAP Theorem
+ The CAP Theorem is the notion that **C** (Consistency), **A** (Availability) and **P** (Partition Tolerance) of data are mutually dependent in a distributed system. Increasing any 2 of these factors will reduce the third. Scylla chooses availability and partition tolerance over consistency. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Cluster
+ One or multiple Scylla nodes, acting in concert, which own a single contiguous token range. State is communicated between nodes in the cluster via the Gossip protocol. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Clustering Key
+ A single or multi-column clustering key determines a row’s uniqueness and sort order on disk within a partition. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Column Family
+ See :term:`table<Table>`.
+
+ Compaction
+ The process of reading several SSTables, comparing the data and time stamps and then writing one SSTable containing the merged, most recent, information. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Compaction Strategy
+ Determines which of the SSTables will be compacted, and when. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Consistency Level (CL)
+ A dynamic value which dictates the number of replicas (in a cluster) that must acknowledge a read or write operation. This value is set by the client on a per operation basis. For the CQL Shell, the consistency level defaults to ONE for read and write operations. See :doc:`Consistency Levels </getting-started/consistency>`.
+
+ Quorum
+ Quorum is a *global* consistency level setting across the entire cluster including all data centers. See :doc:`Consistency Levels </getting-started/consistency>`.
+
+ Date-tiered compaction strategy (DTCS)
+ :abbr:`DTCS (Date-tiered compaction strategy)` is designed for time series data, but should not be used. Use :term:`Time-Window Compaction Strategy`. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Entropy
+ A state where data is not consistent. This is the result when replicas are not synced and data is random. Scylla has measures in place to be antientropic. See :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index>`.
+
+ Eventual Consistency
+ In Scylla, when considering the :term:`CAP Theorem <CAP Theorem>`, availability and partition tolerance are considered a higher priority than consistency.
+
+ Hint
+ A short record of a write request that is held by the co-ordinator until the unresponsive node becomes responsive again, at which point the write request data in the hint is written to the replica node. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Hinted Handoff
+ Reduces data inconsistency which can occur when a node is down or there is network congestion. In Scylla, when data is written and there is an unresponsive replica, the coordinator writes itself a hint. When the node recovers, the coordinator sends the node the pending hints to ensure that it has the data it should have received. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Idempotent
+ Denoting an element of a set which is unchanged in value when multiplied or otherwise operated on by itself. :doc:`Scylla Counters </using-scylla/counters>` are not indepotent because in the case of a write failure, the client cannot safely retry the request.
+
+ JBOD
+ JBOD or Just another Bunch Of Disks is a non-raid storage system using a server with multiple disks in order to instantiate a separate file system per disk. The benefit is that if a single disk fails, only it needs to be replaced and not the whole disk array. The disadvantage is that free space and load may not be evenly distributed. See the :ref:`FAQ <faq-raid0-required>`.
+
+ Keyspace
+ A collection of tables with attributes which define how data is replicated on nodes. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Key Management Interoperability Protocol (KMIP)
+ :abbr:`KMIP (Key Management Interoperability Protocol)` is a communication protocol that defines message formats for storing keys on a key management server (KMIP server). You can use a KMIP server to protect your keys when using Encryption at Rest. See :doc:`Encryption at Rest</operating-scylla/security/encryption-at-rest/>`.
+
+ Leveled compaction strategy (LCS)
+ :abbr:`LCS (Leveled compaction strategy)` uses small, fixed-size (by default 160 MB) SSTables divided into different levels. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Log-structured-merge (LSM)
+ A technique of keeping sorted files and merging them. LSM is a data structure that maintains key-value pairs. See :doc:`Compaction </kb/compaction>`
+
+ Logical Core (lcore)
+ A hyperthreaded core on a hyperthreaded system, or a physical core on a system without hyperthreading.
+
+ MemTable
+ An in-memory data structure servicing both reads and writes. Once full, the Memtable flushes to an :term:`SSTable<SSTable>`. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Mutation
+ A change to data such as column or columns to insert, or a deletion. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Node
+ A single installed instance of Scylla. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Nodetool
+ A simple command-line interface for administering a Scylla node. A nodetool command can display a given node’s exposed operations and attributes. Scylla’s nodetool contains a subset of these operations. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Primary Key
+ In a CQL table definition, the primary key clause specifies the partition key and optional clustering key. These keys uniquely identify each partition and row within a partition. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partition
+ A subset of data that is stored on a node and replicated across nodes. There are two ways to consider a partition. In CQL, a partition appears as a group of sorted rows, and is the unit of access for queried data, given that most queries access a single partition. On the physical layer, a partition is a unit of data stored on a node and is identified by a partition key. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partition Key
+ The unique identifier for a partition, a partition key may be hashed from the first column in the primary key. A partition key may also be hashed from a set of columns, often referred to as a compound primary key. A partition key determines which virtual node gets the first partition replica. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partitioner
+ A hash function for computing which data is stored on which node in the cluster. The partitioner takes a partition key as an input, and returns a ring token as an output. By default Scylla uses the 64 bit Murmurhash3 function and this hash range is numerically represented as a signed 64bit integer, see :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Read Amplification
+ Excessive read requests which require many SSTables. RA is calculated by the number of disk reads per query. High RA occurs when there are many pages to read in order to answer a query. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Read Operation
+ A read operation occurs when an application gets information from an SSTable and does not change that information in any way. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Read Repair
+ An anti-entropy mechanism for read operations ensuring that replicas are updated with most recently updated data. These repairs run automatically, asynchronously, and in the background. See :doc:`Scylla Read Repair </architecture/anti-entropy/read-repair>`.
+
+ Reconciliation
+ A verification phase during a data migration where the target data is compared against original source data to ensure that the migration architecture has transferred the data correctly. See :doc:`Scylla Read Repair </architecture/anti-entropy/read-repair>`.
+
+ Repair
+ A process which runs in the background and synchronizes the data between nodes, so that eventually, all the replicas hold the same data. See :doc:`Scylla Repair </operating-scylla/procedures/maintenance/repair>`.
+
+ Replication
+ The process of replicating data across nodes in a cluster. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Replication Factor (RF)
+ The total number of replica nodes across a given cluster. An :abbr:`RF (Replication Factor)` of 1 means that the data will only exist on a single node in the cluster and will not have any fault tolerance. This number is a setting defined for each keyspace. All replicas share equal priority; there are no primary or master replicas. An RF for any table, can be defined for each :abbr:`DC (Data Center)`. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Shard
+ Each Scylla node is internally split into *shards*, an independent thread bound to a dedicated core.
+ Each shard of data is allotted CPU, RAM, persistent storage, and networking resources which it uses as efficiently as possible.
+ See `Scylla Shard per Core Architecture <https://www.scylladb.com/product/technology/shard-per-core-architecture/>`_ for more information.
+
+ Size-tiered compaction strategy
+ Triggers when the system has enough (four by default) similarly sized SSTables. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Snapshot
+ Snapshots in Scylla are an essential part of the backup and restore mechanism. Whereas in other databases a backup starts with creating a copy of a data file (cold backup, hot backup, shadow copy backup), in Scylla the process starts with creating a table or keyspace snapshot. See :doc:`Scylla Snapshots </kb/snapshots>`.
+
+ Snitch
+ The mapping from the IP addresses of nodes to physical and virtual locations, such as racks and data centers. There are several types of snitches. The type of snitch affects the request routing mechanism. See :doc:`Scylla Snitches </operating-scylla/system-configuration/snitch/>`.
+
+ Space amplification
+ Excessive disk space usage which requires that the disk be larger than a perfectly-compacted representation of the data (i.e., all the data in one single SSTable). SA is calculated as the ratio of the size of database files on a disk to the actual data size. High SA occurs when there is more disk space being used than the size of the data. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ SSTable
+ A concept borrowed from Google Big Table, SSTables or Sorted String Tables store a series of immutable rows where each row is identified by its row key. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`. The SSTable format is a persistent file format. See :doc:`Scylla SSTable Format</architecture/sstable/index>`.
+
+ Table
+ A collection of columns fetched by row. Columns are ordered by Clustering Key. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Time-window compaction strategy
+ TWCS is designed for time series data and replaced Date-tiered compaction. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Token
+ A value in a range, used to identify both nodes and partitions. Each node in a Scylla cluster is given an (initial) token, which defines the end of the range a node handles. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Token Range
+ The total range of potential unique identifiers supported by the partitioner. By default, each Scylla node in the cluster handles 256 token ranges. Each token range corresponds to a Vnode. Each range of hashes in turn is a segment of the total range of a given hash function. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Tombstone
+ A marker that indicates that data has been deleted. A large number of tombstones may impact read performance and disk usage, so an efficient tombstone garbage collection strategy should be employed. See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+
+ Tunable Consistency
+ The possibility for unique, per-query, Consistency Level settings. These are incremental and override fixed database settings intended to enforce data consistency. Such settings may be set directly from a CQL statement when response speed for a given query or operation is more important. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Virtual node
+ A range of tokens owned by a single Scylla node. Scylla nodes are configurable and support a set of :abbr:`Vnodes (virtual nodes)`. In legacy token selection, a node owns one token (or token range) per node. With Vnodes, a node can own many tokens or token ranges; within a cluster, these may be selected randomly from a non-contiguous set. In a Vnode configuration, each token falls within a specific token range which in turn is represented as a Vnode. Each Vnode is then allocated to a physical node in the cluster. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Write Amplification
+ Excessive compaction of the same data. :abbr:`WA (Write amplification)` is calculated by the ratio of bytes written to storage versus bytes written to the database. High WA occurs when there are more bytes/second written to storage than are actually written to the database. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Write Operation
+ A write operation occurs when information is added or removed from an SSTable. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Reshard
+ Splitting an SSTable, that is owned by more than one shard (core), into SSTables that are owned by a single shard. For example: when restoring data from a different server, importing SSTables from Apache Cassandra, or changing the number of cores in a machine (upscale).
+
+ Reshape
+ Rewrite a set of SSTables to satisfy a compaction strategy’s criteria. For example, restoring data from an old backup or before the strategy update.
+
+ Shedding
+ Dropping requests to protect the system. This will occur if the request is too large or exceeds the max number of concurrent requests per shard.
+
+ Dummy Rows
+ Cache dummy rows are entries in the row set, which have a clustering position, although they do not represent CQL rows written by users. Scylla cache uses them to mark boundaries of population ranges, to represent the information that the whole range is complete, and there is no need to go to sstables to read the gaps between existing row entries when scanning.
diff --git a/docs/kb/IP_FWD1.png b/docs/kb/IP_FWD1.png
--- a/docs/kb/IP_FWD1.png
+++ b/docs/kb/IP_FWD1.png
null
diff --git a/docs/kb/Nat_Config.png b/docs/kb/Nat_Config.png
--- a/docs/kb/Nat_Config.png
+++ b/docs/kb/Nat_Config.png
null
diff --git a/docs/kb/_common/kb-article-template.rst b/docs/kb/_common/kb-article-template.rst
--- a/docs/kb/_common/kb-article-template.rst
+++ b/docs/kb/_common/kb-article-template.rst
@@ -0,0 +1,48 @@
+==============================
+Title in Title Caps
+==============================
+
+.. your title should be something customers will search for.
+
+**Topic: subject**
+
+.. Give a subtopic for the title (User Management, Security, Drivers, Automation, Optimization, Schema management, Data Modeling, etc.)
+
+**Learn: topic**
+
+.. in 1-3 words what will users learn by reading this article?
+
+**Audience: Scylla administrators**
+
+.. Choose (Application Developer, Scylla Administrator, Internal, All)
+
+Synopsis
+--------
+
+.. What issue, solution, or problem does this article address
+
+.. TOC for long articles, for short articles you can delete the next 3 lines
+
+
+.. add the rest of your content
+
+Heading 1
+---------
+
+
+Heading 2
+^^^^^^^^^
+
+
+Heading 3
+.........
+
+
+Additional References
+---------------------
+
+* link to reference `Red Hat Enterprise Linux
+ 7 <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/index.html>`__ for example
+
+
+.. add additional resources using the format above, or use other formats. You can get syntax help here: //www.sphinx-doc.org/en/master/
\ No newline at end of file
diff --git a/docs/kb/cdc-experimental-upgrade.rst b/docs/kb/cdc-experimental-upgrade.rst
--- a/docs/kb/cdc-experimental-upgrade.rst
+++ b/docs/kb/cdc-experimental-upgrade.rst
@@ -0,0 +1,27 @@
+===============================
+Upgrading from experimental CDC
+===============================
+
+If you used CDC in Scylla 4.2 or earlier by enabling the experimental feature and you upgrade to 4.3, you must perform additional steps for CDC to work properly.
+
+First, if you enabled CDC on any table (using ``with cdc = { ... }``), you should stop all writes to this table. Then disable CDC before the upgrade:
+
+.. code-block:: none
+
+ alter table ks.t with cdc = {'enabled': false};
+
+.. caution::
+
+ This will delete the CDC log table associated with this table - in this example, ``ks.t_scylla_cdc_log``.
+
+This should work even if you already upgraded, but preferably disable CDC on all tables before the upgrade.
+
+After disabling CDC and finishing the upgrade you can safely reenable it.
+
+The next step is running ``nodetool checkAndRepairCdcStreams``. Up to this point, Scylla may have periodically reported the following errors in its logs:
+
+.. code-block:: none
+
+ cdc - Could not retrieve CDC streams with timestamp {...} upon gossip event. Reason: "std::runtime_error (Could not find CDC generation with timestamp ... in distributed system tables (current time: ...), even though some node gossiped about it.)". Action: not retrying.
+
+After running the ``nodetool`` command the errors should not appear anymore. If they do, please open an issue.
diff --git a/docs/kb/compaction-incremental.png b/docs/kb/compaction-incremental.png
--- a/docs/kb/compaction-incremental.png
+++ b/docs/kb/compaction-incremental.png
null
diff --git a/docs/kb/compaction-leveled.png b/docs/kb/compaction-leveled.png
--- a/docs/kb/compaction-leveled.png
+++ b/docs/kb/compaction-leveled.png
null
diff --git a/docs/kb/compaction-size-tiered.png b/docs/kb/compaction-size-tiered.png
--- a/docs/kb/compaction-size-tiered.png
+++ b/docs/kb/compaction-size-tiered.png
null
diff --git a/docs/kb/compaction.rst b/docs/kb/compaction.rst
--- a/docs/kb/compaction.rst
+++ b/docs/kb/compaction.rst
@@ -0,0 +1,249 @@
+Compaction
+==========
+
+
+This document gives a high level overview of Compaction, focusing on what compaction is, and how it works. There is a different document that covers the :doc:`CQL syntax </getting-started/compaction>` for setting a compaction strategy. There is also another document, :doc:`Compaction Strategy Matrix </architecture/compaction/compaction-strategies>`, that covers how to decide which strategy works best.
+
+How Scylla Writes Data
+----------------------
+
+Scylla’s write path follows the well-known **Log Structured Merge (LSM)** design for efficient writes that are immediately available for reads. Scylla is not the first project to use this method. Popular projects to use this method include Lucene Search Engine, Google BigTable, and Apache Cassandra.
+
+Scylla writes its updates to a :term:`memory table (MemTable)<MemTable>`, and when that becomes too big, it is flushed to a new file. This file is sorted to make it easy to search and later merge. This is why the tables are known as Sorted String Tables or :term:`SSTables<SSTable>`.
+
+.. image:: write-path-image-memtable-sstable.png
+
+In time, two major problems start to appear. First, data in one SSTable which is later modified or deleted in another SSTable wastes space as both tables are present in the system. Second, when data is split across many SSTables, read requests are processed slower as many SSTables need to be read. Scylla mitigates the second problem by using a bloom filter and other techniques to avoid reading from SSTables that do not include the desired partition. However, as the number of SSTables grows, inevitably so do the number of disk blocks from which we need to read on every read query. For these reasons, as soon as enough SSTables have accumulated, Scylla performs a :term:`compaction<Compaction>`.
+
+
+Compaction Overview
+-------------------
+
+Compaction merges several SSTables into new SSTable(s) which contain(s) only the live data from the input SSTables. Merging several sorted files to get a sorted result is an efficient process, and this is the main reason why SSTables are kept sorted.
+
+There are two types of compactions:
+
+* Minor Compaction
+ Scylla automatically triggers a compaction of some SSTables, according to a :term:`compaction strategy<Compaction Strategy>` (as described below). This is the recommended method.
+
+* Major Compaction
+ A user triggers (using nodetool) a compaction over all SSTables, merging the individual tables according to the selected compaction strategy.
+
+.. caution:: It is always best to allow Scylla to automatically run minor compactions. Major compactions can exhaust resources, increase operational costs, and take up valuable disk space. This requires you to have 50% more disk space than your data unless you are using `Incremental compaction strategy (ICS)`_.
+
+View Compaction Statistics
+--------------------------
+
+Scylla has tools you can use to see the status of your compactions. These include nodetool (:doc:`compactionhistory </operating-scylla/nodetool-commands/compactionhistory>` and :doc:`compactionstats </operating-scylla/nodetool-commands/compactionstats>`) and the Grafana dashboards which are part of the `Scylla Monitoring Stack <https://monitoring.docs.scylladb.com/>`_ which display the compaction statistics on a per cluster and per node basis. Compaction errors can be seen in the :ref:`logs <manager-2.1-logging-settings>`.
+
+Compaction strategy
+-------------------
+
+A compaction strategy is what determines which of the SSTables will be compacted, and when. The following compaction strategies are available and are described in greater detail below. For a matrix which compares each strategy to its workload, refer to :doc:`Compaction Strategy Matrix </architecture/compaction/compaction-strategies>`
+
+* `Size-tiered compaction strategy (STCS)`_ - (default setting) triggered when the system has enough similarly sized SSTables.
+* `Leveled compaction strategy (LCS)`_ - the system uses small, fixed-size (by default 160 MB) SSTables divided into different levels and lowers both Read and Space Amplification.
+* `Incremental compaction strategy (ICS)`_ - Available for Enterprise customers, uses runs of sorted, fixed size (by default 1 GB) SSTables in a similar way that LCS does, organized into size-tiers, similar to STCS size-tiers. If you are an Enterprise customer ICS is an updated strategy meant to replace STCS. It has the same read and write amplification, but has lower space amplification due to the reduction of temporary space overhead is reduced to a constant manageable level.
+* `Time-window compaction strategy (TWCS)`_ - designed for time series data and puts data in time order. This strategy replaced Date-tiered compaction. TWCS uses STCS to prevent accumulating SSTables in a window not yet closed. When the window closes, TWCS works towards reducing the SSTables in a time window to one.
+* `Date-tiered compaction strategy (DTCS)`_ - designed for time series data, but TWCS should be used instead.
+
+How to Set a Compaction Strategy
+................................
+
+Compaction strategies are set as part of the ``CREATE`` or ``ALTER`` statement when creating or altering tables. Refer to the :doc:`CQL syntax </getting-started/compaction>` for details.
+
+.. caution:: Changing the parameters for compaction strategies or changing from one strategy to another (using the ``ALTER`` statement) can create issues. See `Changing Compaction Strategies or Properties`_ for more information.
+
+.. _size-tiered-compaction-strategy-stcs:
+
+Size-tiered Compaction Strategy (STCS)
+--------------------------------------
+
+The premise of ``SizeTieredCompactionStrategy`` (STCS) is to merge SSTables of approximately the same size.
+All SSTables are put into different buckets depending on their size.
+An SSTable is added to an existing bucket if size of the SSTable is within the parameters: :ref:`bucket_low <stcs-options>` and :ref:`bucket_high <stcs-options>`, which is based on calculating the current average size of the SSTables already in the bucket.
+
+This will create several buckets and when the threshold number of tables(``min_threshold``) within a bucket is reached, the tables in that bucket are compacted.
+Following the compaction, the tables are merged, resulting in one larger SSTable. As time progresses and several large SSTables have accumulated, they will be merged to form one even-larger SSTable and so on.
+
+This means that the system has several size tiers/buckets (small SSTables, large SSTables, even-larger SSTables) and in each tier, there is roughly the same number of SSTables. When one tier is full (the threshold has been reached), the system merges all its tables to create one SSTable which falls roughly into the next size tier.
+
+.. image:: compaction-size-tiered.png
+
+.. _leveled-compaction-strategy-lcs:
+
+Leveled Compaction Strategy (LCS)
+---------------------------------
+
+Leveled Compaction uses small, fixed-size (by default 160 MB) SSTables divided into different levels. Each level represents a run of a number of SSTables.
+
+A run of SSTables
+.................
+
+A **run** is a :term:`log-structured-merge (LSM)<Log-structured-merge (LSM)>` term for a large SSTable split into several smaller SSTables. In other words, a run is a collection of SSTables with non-overlapping key ranges. The benefit of a run is that when a compaction is done, only parts of it (small individual SSTables) are compacted and deleted. Following a compaction, SSTables are smaller and there is no need to compact a huge SSTable all at once.
+
+.. image:: compaction-leveled.png
+
+
+The compaction method works as follows:
+
+1. New SSTables (created from MemTables) are created in **Level 0**. All other levels are each a run of SSTables, of exponentially increasing size as follows:
+
+ - **Level 1** is a run of 10 SSTables (160 MB each table * 10)
+ - **Level 2** is a run of 100 SSTables (160 MB each table * 100), etc.
+
+2. When there are 4 SSTables in Level 0, they are compacted with the 10 SSTables in Level 1. This compaction works as follows:
+
+ - Read in parallel 4 SSTables in level 0 and 10 in Level 1.
+ - Write new SSTables for Level 1 (replacing the 10 old tables which were compacted).
+ - Instead of creating one large SSTable, several SSTables are written as follows: One SSTable is created. When it reaches the size limit (160 MB), a new table starts. As the data is merged on the sorted keys, this generates a run (see `A run of SSTables`_), with non-overlapping key ranges.
+
+3. If after the compaction from Level 0 into Level 1, if there are at least 10 SSTables in Level 1, the excess SSTables from Level 1 are compacted and put into Level 2 as follows:
+
+ - Take one SSTable from Level 1 (this SSTable will be deleted after the compaction)
+ - Look at this SSTable’s key range, and find all SSTables in Level 2 which overlap with it. Typically, there are about 12 of these (the Level 1 SSTable spans roughly 1/10th of the keys, while each Level 2 SSTable spans roughly 1/100th of the keys, so 10 Level 2 SSTables will overlap the Level 1 SSTable’s range, plus two more on the edges).
+ - As before, compact the 1 SSTable from Level 1 and the 12 SSTables from Level 2 and create new SSTables in Level 2 (and delete the 1+12 original SSTables).
+ - If after this compaction of Level 1 into Level 2, there are excess SSTables in Level 2 (as Level 2 can only take 100 tables), merge them into Level 3.
+
+.. _temporary-fallback-to-stcs:
+
+Temporary Fallback to STCS
+..........................
+
+When new data is written very quickly, the Leveled Compaction strategy may be temporarily unable to keep up with the demand. This can result in an accumulation of a large number of SSTables in L0 which in turn create very slow reads as all read requests read from all SSTables in L0. So as an emergency measure, when the number of SSTables in L0 grows to 32, LCS falls back to STCS to quickly reduce the number of SSTables in L0. Eventually, LCS will move this data again to fixed-sized SSTables in higher levels.
+
+Likewise, when :term:`bootstrapping<Bootstrap>` a new node, SSTables are streamed from other nodes. The level of the remote SSTable is kept to avoid many compactions until after the bootstrap is done. During the bootstrap, the new node receives regular write requests while it is streaming the data from the remote node. Just like any other write, these writes are flushed to L0. If Scylla did an LCS compaction on these L0 SSTables and created SSTables in higher level, this could have blocked the remote SSTables from going to the correct level (remember that SSTables in a run must not have overlapping key ranges). To remedy this from happening, Scylla compacts the tables using STCS only in L0 until the bootstrap process is complete. Once done, all resumes as normal under LCS.
+
+.. _incremental-compaction-strategy-ics:
+
+Incremental Compaction Strategy (ICS)
+-------------------------------------
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. include:: /rst_include/enterprise-only-note.rst
+
+One of the issues with Size-tiered compaction is that it needs temporary space because SSTables are not removed until they are fully compacted. ICS takes a different approach and splits each large SSTable into a run of sorted, fixed-size (by default 1 GB) SSTables (a.k.a. fragments) in the same way that LCS does, except it treats the entire run and not the individual SSTables as the sizing file for STCS. As the run-fragments are small, the SSTables compact quickly, allowing individual SSTables to be removed as soon as they are compacted. This approach uses low amounts of memory and temporary disk space.
+
+ICS uses the same philosophy as STCS, where the SSTables are sorted in buckets according to their size. However, unlike STCS, ICS compaction uses SSTable runs as input, and produces a new run as output. It doesn't matter if a run is composed of only one fragment that could have come from STCS migration. From an incremental compaction perspective, everything is a run.
+
+The strategy works as follows:
+
+#. ICS looks for candidates for compaction that are similar in size. These candidates are called ``Input Runs``.
+
+ * The input runs may contain one or more SSTables each.
+
+#. ICS compacts two or more similar-sized input runs into a single ``Output run`` (* See note_ ).
+#. Incremental Compaction progressively works on two or more fragments at a time, one from each input run.
+
+ * It reads mutations from all input fragments and merges them together into a single output fragment.
+ * As long as the resulting fragment is smaller than the ``sstable_size_in_mb``, no further action is needed.
+ * If the fragment is larger than the ``sstable_size_in_mb``:
+
+ 1. Stop when the size threshold is reached, and seal the output fragment.
+ 2. Create a new run fragment and continue compacting the remaining input fragments, until the size threshold is reached.
+ 3. When an input fragment is exhausted, take it out of the list of SSTables to compact, and delete it from disk.
+ 4. Repeat until there are no input fragments left.
+
+#. Take all of the output fragments and feed them back into compaction as an SSTable run.
+#. Stop when all fragments from input runs were exhausted and released.
+
+.. _note:
+.. note:: To prevent data resurrection in case scylla crashes in the middle of compaction, ICS may possibly write an auxiliary run containing purgeable tombstones in addition to the output run containing live data.
+ These tombstones are kept on disk while there are SSTables containing data that the tombstones may shadow. Once compaction is done, deleting all shadowed data from all SSTables, the purgeable tombstones are purged and the SSTables holding them are removed from storage.
+
+.. image:: ics-incremental-compaction.png
+
+Incremental compaction as a solution for temporary space overhead in STCS
+.........................................................................
+
+We fixed the temporary space overhead on STCS by applying the incremental compaction approach to it, which resulted in the creation of Incremental Compaction Strategy (ICS). The compacted SSTables, that become increasingly larger over time with STCS, are replaced with sorted runs of SSTable fragments, together called “SSTable runs” – which is a concept borrowed from Leveled Compaction Strategy (LCS).
+
+Each fragment is a roughly fixed size (aligned to partition boundaries) SSTable and it holds a unique range of keys, a portion of the whole SSTable run. Note that as the SSTable-runs in ICS hold exactly the same data as the corresponding SSTables created by STCS, they become increasingly longer over time (holding more fragments), in the same way that SSTables grow in size with STCS, yet the ICS SSTable fragments’ size remains the same.
+
+For example, when compacting two SSTables (or SSTable runs) holding 7GB each: instead of writing up to 14GB into a single SSTable file, we’ll break the output SSTable into a run of 14 x 1GB fragments (fragment size is 1GB by default).
+
+.. image:: compaction-incremental.png
+
+.. _time-window-compactionstrategy-twcs:
+
+Time-window Compaction Strategy (TWCS)
+--------------------------------------
+
+Time-window compaction strategy was introduced as a replacement for `Date-tiered Compaction Strategy (DTCS)`_ for handling time series workloads. Time-Window Compaction Strategy compacts SSTables within each time window using `Size-tiered Compaction Strategy (STCS)`_. SSTables from different time windows are never compacted together.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+The strategy works as follows:
+
+1. A time window is configured. The window is determined by the compaction window size :ref:`compaction_window_size <twcs-options>` and the time unit (:ref:`compaction_window_unit <twcs-options>`).
+2. SSTables created within the time window are compacted using `Size-tiered Compaction Strategy (STCS)`_.
+3. Once a time window ends, take all SSTables which were created during the time window and compact the data into one SSTable.
+4. The final resulting SSTable is never compacted with other time-windows’ SSTables.
+
+With this explanation, if the time window was for one day, at the end of the day, the SSTables accumulated for that day only would be compacted into one SSTable.
+
+When time-series data gets out of order
+.......................................
+
+The primary motivation for TWCS is to separate data on disk by timestamp and to allow fully expired SSTables to drop more efficiently. This efficiency stops when data is written to SSTables out of order, with new data and old data in the same SSTable. Out of order data can appear in the same SSTable in two ways:
+
+* If the user mixes old data and new data in the traditional write path, the data is commingled in the MemTables and flushed into the same SSTable, where it will remain commingled.
+* If the user’s read requests for old data causes read repairs that pull the old data into the current MemTable. The data is commingled in the MemTables and flushed into the same SSTable, where it will remain commingled.
+
+While TWCS tries to minimize the impact of commingled data, users should attempt to avoid this behavior. Specifically, users should avoid queries that explicitly set the timestamp. It is recommended to run frequent repairs (which streams data in such a way that it does not become commingled), and disable background read repair by setting the table’s :ref:`read_repair_chance <create-table-general-options>` and :ref:`dclocal_read_repair_chance <create-table-general-options>` to ``0``.
+
+
+Date-tiered compaction strategy (DTCS)
+--------------------------------------
+
+Date-Tiered Compaction is designed for time series data. It is only suitable for time-series data. This strategy has been replaced by `Time-window compaction strategy (TWCS)`_.
+
+Date-tiered compaction strategy works as follows:
+
+* First it sorts the SSTables by time and then compacts adjacent (time-wise) SSTables.
+* This results in SSTables whose sizes increase exponentially as they grow older.
+
+For example, at some point we can have the last minute of data in one SSTable (by default, base_time_seconds = 60), another minute before that in another SSTable, then the 4 minutes before that in one SSTable, then the 4 minutes before that, then an SSTable of the 16 minutes before that, and so on. This structure can easily be maintained by compaction, very similar to size-tiered compaction. When there are 4 (the default value for min_threshold) small (one-minute) consecutive SSTables, they are compacted into one 4-minute SSTable. When there are 4 of the bigger SSTables one after another (time-wise), they are merged into a 16-minute SSTable, and so on.
+
+Antique SSTables older than ``max_SSTable_age_days`` (by default 365 days) are not compacted as doing these compactions would not be useful for most queries, the process would be very slow, and the compaction would require huge amounts of temporary disk space.
+
+
+Changing Compaction Strategies or Properties
+--------------------------------------------
+
+Changing the Threshold in LCS
+.............................
+
+There can be cases where, following a compaction, tables are created in a level which are not compacted for a considerable amount of time.
+For example, a user has tables which are using LCS. There are 5 levels of tables at present and the ``SSTable_size_in_mb`` is 5MB. The user changes this threshold to 160MB. Following this change, there is only enough data to actually get an L3 on the same node. The data in the SSTables in L4 will get starved and will not get compacted. To avoid this, LCS tries to include those starved high level SSTables in future compactions. If after been 25 compaction rounds, a level was not compacted, it is brought in to the next compaction.
+
+Changing to Time Window Compaction Strategy (TWCS)
+..................................................
+
+If you want to enable TWCS on existing data, you may consider running a major compaction first, placing all existing data into a single (old) window. Subsequent newer writes will then create typical SSTables as expected.
+
+Changing the Time Window in TWCS
+................................
+
+If you want to change the time window you can do so, but keep in mind that this change may trigger additional compactions as adjacent windows are joined together. If the window size is decreased (for example, from 24 hours to 12 hours), then the existing SSTables will not be modified. Note as well that TWCS can not split existing SSTables into multiple windows.
+
+
+Which Strategy is best to use
+-----------------------------
+Use the table in :ref:`Which strategy is best <which-strategy-is-best>` to determine the right strategy for your needs.
+
+
+
+
+References
+----------
+* :doc:`CQL Reference for Compaction </getting-started/compaction>`
+
+* :doc:`How to Choose a Compaction Strategy </architecture/compaction/compaction-strategies>`.
+
+* `Blog: Scylla’s Compaction Strategies Series: Write Amplification in Leveled Compaction <https://www.scylladb.com/2018/01/31/compaction-series-leveled-compaction/>`_
+
+* `Blog: Scylla’s Compaction Strategies Series: Space Amplification in Size-Tiered Compaction <https://www.scylladb.com/2018/01/17/compaction-series-space-amplification/>`_
+
+* Size Tiered: `Shrikant Bang’s Notes <https://shrikantbang.wordpress.com/2014/04/22/size-tiered-compaction-strategy-in-apache-cassandra/>`_
diff --git a/docs/kb/count-all-rows.rst b/docs/kb/count-all-rows.rst
--- a/docs/kb/count-all-rows.rst
+++ b/docs/kb/count-all-rows.rst
@@ -0,0 +1,23 @@
+====================================
+Counting all rows in a table is slow
+====================================
+
+**Audience: Scylla users**
+
+Trying to count all rows in a table using
+
+.. code-block:: cql
+
+ SELECT COUNT(1) FROM ks.table;
+
+often fails with **ReadTimeout** error.
+
+COUNT() is running a full-scan query on all nodes, which might take a long time to finish. Often the time is greater than Scylla query timeout.
+One way to bypass this in Scylla 4.4 or later is increasing the timeout for this query using the :ref:`USING TIMEOUT <using-timeout>` directive, for example:
+
+
+.. code-block:: cql
+
+ SELECT COUNT(1) FROM ks.table USING TIMEOUT 120s;
+
+You can also get an *estimation* of the number **of partitions** (not rows) with :doc:`nodetool tablestats </operating-scylla/nodetool-commands/tablestats>`
diff --git a/docs/kb/cqlsh-more.rst b/docs/kb/cqlsh-more.rst
--- a/docs/kb/cqlsh-more.rst
+++ b/docs/kb/cqlsh-more.rst
@@ -0,0 +1,19 @@
+=============================================
+CQL Query Does Not Display Entire Result Set
+=============================================
+
+**Audience: Scylla administrators**
+
+If you send a cqlsh query similar to:
+
+.. code-block:: none
+
+ SELECT * FROM 'keyspace.table' limit 100;
+
+and the results show a single row with ``--More--``, the ``--More--`` indicates that there are additional pages - if you click Enter, additional rows are displayed.
+
+As the query is using paging (from cqlsh by default page size is 100) - Scylla uses this information internally and will fetch internally page size results. Some of these may be discarded and not returned to you or the output may reveal blank pages where you will see the ``--More--`` prompt causing you to page through empty pages. Neither of these outputs is desired.
+
+If you need text result of this query as a single run, without the page delimiter, you can :ref:`turn off paging <cqlsh-paging>`.
+
+It is also recommended to turn ``tracing on`` (please keep the limit to 100 as well).
diff --git a/docs/kb/cqlsh-results.rst b/docs/kb/cqlsh-results.rst
--- a/docs/kb/cqlsh-results.rst
+++ b/docs/kb/cqlsh-results.rst
@@ -0,0 +1,29 @@
+
+================================================================
+When CQLSh query returns partial results with followed by "More"
+================================================================
+
+
+.. your title should be something customers will search for.
+
+**Topic: When results are missing from query**
+
+
+**Audience: Scylla administrators**
+
+Synopsis
+---------
+
+If you send a cqlsh query similar to:
+
+.. code-block:: none
+
+ SELECT * FROM 'keyspace.table' limit 100;
+
+and the results show a single row with ``--More``, the ``--More--`` indicates that there are additional pages - if you click Enter, additional rows are displayed.
+
+As the query is using paging (from cqlsh by default page size is 100) - Scylla uses this information internally and will fetch internally page size results. Some of these may be discarded and not returned to you or the output may reveal blank pages where you will see the ``more`` prompt causing you to page through empty pages. Neither of these outputs is desired.
+
+If you need this in query as a single result you can turn off paging and include paging off in the query.
+
+It is also recommended to turn tracing on (please keep the limit to 100 as well).
diff --git a/docs/kb/custom-user.rst b/docs/kb/custom-user.rst
--- a/docs/kb/custom-user.rst
+++ b/docs/kb/custom-user.rst
@@ -0,0 +1,55 @@
+Run Scylla and supporting services as a custom user:group
+=========================================================
+**Topic: Planning and setup**
+By default, Scylla runs as user ``scylla`` in group ``scylla``. The following procedure will allow you to use a custom user and group to run Scylla.
+1. Create the new user and update file permissions
+
+.. code-block:: sh
+
+ useradd test
+ groupadd test
+ usermod test -G test
+ chown -R test:test /var/lib/scylla
+
+2. Edit ``/etc/sysconfig/scylla-server`` and change the USER and GROUP
+
+.. code-block:: sh
+
+ USER=test
+ GROUP=test
+
+3. Edit ``/etc/systemd/system/multi-user.target.wants/scylla-server.service``
+
+.. code-block:: sh
+
+ User=test
+
+4. Edit ``/etc/systemd/system/multi-user.target.wants/node-exporter.service``
+
+.. code-block:: sh
+
+ User=test
+ Group=test
+
+5. Edit /usr/lib/systemd/system/scylla-jmx.service
+
+.. code-block:: sh
+
+ User=test
+ Group=test
+
+6. Reload the daemon settings and start Scylla and node_exporter
+
+.. code-block:: sh
+
+ systemctl daemon-reload
+ systemctl start scylla-server
+ systemctl start node-exporter
+
+At this point, all services should be started as test:test user:
+
+.. code-block:: sh
+
+ test 8760 1 11 14:42 ? 00:00:01 /usr/bin/scylla --log-to-syslog 1 --log-to-std ...
+ test 8765 1 12 14:42 ? 00:00:01 /opt/scylladb/jmx/symlinks/scylla-jmx -Xmx256m ...
+ test 13638 1 0 14:30 ? 00:00:00 /usr/bin/node_exporter --collector.interrupts
diff --git a/docs/kb/decode-stack-trace.rst b/docs/kb/decode-stack-trace.rst
--- a/docs/kb/decode-stack-trace.rst
+++ b/docs/kb/decode-stack-trace.rst
@@ -0,0 +1,151 @@
+=====================
+Decoding Stack Traces
+=====================
+
+**Topic: Decoding stack traces in Scylla logs**
+
+**Environment: Any Scylla setup on any supported OS**
+
+**Audience: All**
+
+Synopsis
+--------
+
+This article describes how to decode the stack traces found in Scylla logs.
+
+
+What are Stack Traces?
+----------------------
+
+Stack traces can appear in the logs due to various errors or in the course of regular database operation. It is useful to be able to decode the trace in order to understand what exactly happened. Decoding the stack trace requires the Debug binaries for the specific Scylla build and OS in use are installed.
+
+Note that sharing the stack trace as part of your support ticket or Github issue, helps the Scylla support team to understand the issue better.
+
+
+Install Debug Binary files
+--------------------------
+
+Install the Debug binaries according to your OS distribution
+
+.. tabs::
+
+ .. group-tab:: RPM based distributions
+
+ For Scylla Enterprise:
+
+ .. code-block:: none
+
+ yum install scylla-enterprise-debuginfo
+
+ For Scylla Open Source:
+
+ .. code-block:: none
+
+ yum install scylla-debuginfo
+
+ .. group-tab:: DEB based distributions
+
+ For Scylla Enterprise:
+
+ .. code-block:: none
+
+ apt-get install scylla-enterprise-server-dbg
+
+ For Scylla Open Source:
+
+ .. code-block:: none
+
+ apt-get install scylla-server-dbg
+
+
+Validate the debug binary file name
+-----------------------------------
+
+To later determine the actual debug binary, look in the ``/usr/lib/debug/`` directory
+for a file named scylla.debug.
+
+For example:
+
+.. code-block:: none
+
+ # find /usr/lib/debug/ | grep scylla.debug
+ /usr/lib/debug/usr/bin/scylla.debug
+
+Locate and Analyze the Logs
+----------------------------
+
+**Procedure**
+
+#. Copy the stack from the :doc:`system log </getting-started/logging>` and place it in a file (trace.txt, for example).
+
+ .. code-block:: none
+
+ Jul 14 16:56:50 hostname01 scylla: Aborting on shard 8.
+ Jul 14 16:56:50 hostname01 scylla: Backtrace:
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000688602
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a36fc
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a39a5
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a3a53
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libpthread.so.0+0x000000000000f6cf
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x0000000000036276
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x0000000000037967
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024ce37b
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024d2a47
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024df1d5
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000023dccec
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000023feac1
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024324b9
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024357e4
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000001eace90
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000001eaf944
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000584ab6
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000584c71
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000006522ff
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000006554e5
+ Jul 14 16:56:50 hostname01 scylla: 0x000000000073d3cd
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libpthread.so.0+0x0000000000007e24
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x00000000000febac
+
+
+
+#. Locate the files for backtrace.
+
+ .. code-block:: shell
+
+ find . -name "scylla*.debug"
+
+ With Scylla 4.1 for example, returns:
+
+ .. code-block:: shell
+
+ /usr/lib/debug/opt/scylladb/libexec/scylla-4.1.1-0.20200703.1d9bbbc9577.x86_64.debug
+
+#. Run the decoder:
+
+ .. code-block:: none
+
+ ./seastar-addr2line -e /usr/lib/debug/usr/bin/scylla.debug -f trace.txt > trace_decoded.txt
+
+ ``trace_decoded.txt`` now contains the decoded version of the stack trace:
+
+ For example:
+
+ .. code-block:: none
+
+ void seastar::backtrace<seastar::backtrace_buffer::append_backtrace()::{lambda(seastar::frame)#1}>(seastar::backtrace_buffer::append_backtrace()::{lambda(seastar::frame)#1}&&) at /usr/src/debug/scylla-4.1.1/seastar/util/backtrace.hh:56
+ seastar::backtrace_buffer::append_backtrace() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:390
+ (inlined by) print_with_backtrace at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:411
+ seastar::print_with_backtrace(char const*) at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:418
+ sigabrt_action at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3939
+ (inlined by) operator() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3921
+ (inlined by) _FUN at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3917
+ ...
+
+ seastar::reactor::run_tasks(seastar::reactor::task_queue&) at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:2621
+ seastar::reactor::run_some_tasks() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3033
+ seastar::reactor::run_some_tasks() at /opt/scylladb/include/c++/7/chrono:377
+ (inlined by) seastar::reactor::run() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3180
+
+
+
+
diff --git a/docs/kb/disk-utilization.rst b/docs/kb/disk-utilization.rst
--- a/docs/kb/disk-utilization.rst
+++ b/docs/kb/disk-utilization.rst
@@ -0,0 +1,50 @@
+===============================
+Snapshots and Disk Utilization
+===============================
+
+**Topic: nodetool snapshot and disk space**
+
+**Learn: understand how nodetool snapshot utilizes disk space**
+
+**Audience: Scylla administrators**
+
+
+When you create a snapshot using :doc:`nodetool snapshot </operating-scylla/nodetool-commands/snapshot>` command, Scylla is not going to copy existing SStables to the snapshot directory as one could have expected. Instead, it is going to create hard links to them. While this may seem trivial, what should be noted is the following:
+
+* The snapshot disk space at first will start at zero and will grow to become equal to the size of the node data set when the snapshot was created. So at the beginning there will not be any significant increase in the disk space utilization.
+* While it may seem plausible to believe that the snapshot image is immediately created, the snapshot eventually grows to its expected size
+* Background compactions will delete data from SSTables as normal, but any table with a hard link (part of the snapshot) will not be deleted. This will take up disk space.
+* This in particular means that once you have created the snapshot, its “true size” begins at zero and will eventually become equal to the size of the node data set when the snapshot was created.
+
+
+In this example, a snapshot was created. As you can see, its ``True size`` value is 0 bytes:
+
+.. code-block:: none
+
+ nodetool listsnapshots
+ Snapshot Details:
+
+ Snapshot name Keyspace name Column family name True size Size on disk
+ 1574708464997 ks3 standard1 0 bytes 2.23 GB
+
+ Total TrueDiskSpaceUsed: 0 bytes
+
+After time, you can see its ``True size`` is the same as the space it utilizes on disk:
+
+.. code-block:: none
+
+ nodetool compact ks3
+ nodetool listsnapshots
+
+ Snapshot Details:
+ Snapshot name Keyspace name Column family name True size Size on disk
+ 1574708464997 ks3 standard1 2.23 GB 2.23 GB
+
+ Total TrueDiskSpaceUsed: 2.23 GiB
+
+.. note:: A major compaction makes the true snapshot size jump to the data size immediately as the old SSTables are being deleted.
+
+
+Additional References
+---------------------
+* :doc:`Nodetool Snapshoot </operating-scylla/nodetool-commands/snapshot>`
diff --git a/docs/kb/dpdk-hardware.rst b/docs/kb/dpdk-hardware.rst
--- a/docs/kb/dpdk-hardware.rst
+++ b/docs/kb/dpdk-hardware.rst
@@ -0,0 +1,37 @@
+DPDK mode
+=========
+**Topic: Planning and setup**
+
+**Learn: How to select networking hardware for Scylla**
+
+**Audience: Scylla administrators**
+
+Scylla is designed to use the Seastar framework, which uses the Data Plane Development Kit (DPDK) to drive NIC hardware directly, instead of relying on the kernel’s network stack. This provides an enormous performance boost for Scylla. Scylla and DPDK also rely on the Linux “hugepages” feature to minimize overhead on memory allocations. DPDK is supported on a variety of high-performance network devices.
+
+.. role:: raw-html(raw)
+ :format: html
+
++------+---------------------------------------------------+--------------------------------------+
+|Brand |Device | Status |
++======+===================================================+======================================+
+|Intel |ixgbe (82598..82599, X540, X550) | :raw-html:`<span class="icon-yes"/>` |
++------+---------------------------------------------------+--------------------------------------+
+|Intel |i40e (X710, XL710) | :raw-html:`<span class="icon-yes"/>` |
++------+---------------------------------------------------+--------------------------------------+
+
+Scylla RPM packages are built with DPDK support, but the package defaults to POSIX networking mode (see Administration Guide). To enable DPDK, edit ``/etc/sysconfig/scylla-server`` and edit the following lines:
+
+.. code-block:: ini
+
+ # choose following mode: virtio, dpdk, posix
+ NETWORK_MODE=posix
+
+ # Ethernet device driver (dpdk)
+ ETHDRV=
+
+Reference
+---------
+`DPDK: Supported NICs <http://dpdk.org/doc/nics>`_
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/flamegraph.rst b/docs/kb/flamegraph.rst
--- a/docs/kb/flamegraph.rst
+++ b/docs/kb/flamegraph.rst
@@ -0,0 +1,53 @@
+=====================================
+Debug your database with Flame Graphs
+=====================================
+
+Flame Graphs are used as a debugging tool to identify latency and the part of the execution path that takes most of the CPU time.
+Use Flame Graphs when you:
+
+* Need to understand which Scylla code path/functions are using the most time. For instance, when you have latency issues.
+* Need to compare time spent in particular Scylla code paths/functions on different shards. For instance, when you have latency issues on one CPU but not on the other.
+
+Run a Flame Graph
+-----------------
+
+**Procedure**
+
+#. Install flamegraph and flamegraph-stackcollapse-perf
+
+ From DNF
+
+ .. code-block:: shell
+
+ dnf install flamegraph.noarch flamegraph-stackcollapse-perf.noarch
+
+ If the above packages are not available in you distribution's repositories, you can clone the FlameGraph git repository
+
+ .. code-block:: shell
+
+ git clone https://github.com/brendangregg/FlameGraph
+ cd FlameGraph
+
+#. Run the following perf commands, using :doc:`Map CPU to Scylla Shards </kb/map-cpu>` and :doc:`Using the perf utility with Scylla </kb/use-perf>` for reference.
+
+ .. code-block:: shell
+
+ sudo perf record --call-graph dwarf -C <CPU on which you are onrecording>
+ sudo perf script | stackcollapse-perf.pl | flamegraph.pl > some_name.svg
+
+#. The result is an .svg file that is not just a picture but a dynamic diagram where you can search, zoom in, and zoom out. In order to enjoy a Flame Graph properly with all of its features you can open it in a browser such as Chrome or Firefox.
+
+
+.. image:: flamegraph.svg
+
+Tips
+----
+
+* On the CPU you are recording, try to load Scylla to consume 100% of the CPU runtime. Otherwise you’ll see a lot of OS functions related to the idle time handling
+
+* Recording on all shards (e.g. using “perf record” -p parameter) may lead to confusing results recording the same symbol called from different threads (shards). This is not recommended.
+
+
+
+
+
diff --git a/docs/kb/flamegraph.svg b/docs/kb/flamegraph.svg
--- a/docs/kb/flamegraph.svg
+++ b/docs/kb/flamegraph.svg
null
diff --git a/docs/kb/gc-grace-seconds.rst b/docs/kb/gc-grace-seconds.rst
--- a/docs/kb/gc-grace-seconds.rst
+++ b/docs/kb/gc-grace-seconds.rst
@@ -0,0 +1,43 @@
+==========================================
+How to Change gc_grace_seconds for a Table
+==========================================
+
+.. your title should be something customers will search for.
+
+**Topic: subject**
+
+How to change (reduce) gc_grace_seconds parameter of the table
+
+**Audience: Scylla administrators**
+
+
+Issue
+-----
+
+When you want to change the ``gc_grace_seconds`` parameter value for a particular table you should readjust your repairs frequency to have at
+least one successful full repair for the table in question every (new) ``gc_grace_seconds`` window as discussed `here <https://university.scylladb.com/courses/scylla-operations/lessons/repair-tombstones-and-scylla-manager/topic/repair-tombstones-and-scylla-manager/>`_
+in order to avoid data resurrection.
+
+In addition, you should follow the procedure below in order to avoid data resurrection after the changing the ``gc_grace_seconds`` and before the next repair.
+
+
+Resolution
+----------
+#. Run a :doc:`full repair </operating-scylla/manager/2.1/repair>` for the table in question.
+#. Change the ``gc_grace_seconds`` value for the table using the :ref:`ALTER table <alter-table-statement>` command.
+#. Verify that the schema is in sync after the change by issuing :doc:`nodetool describecluster </operating-scylla/nodetool-commands/describecluster>` command from all nodes.
+ Verify that only a single schema version is reported. Read the :doc:`Schema Mismatch Troubleshooting Guide </troubleshooting/error-messages/schema-mismatch>` if it's not the case.
+#. Make sure that you run at least one :doc:`full repair </operating-scylla/manager/2.1/repair>` for the table in question during the ``gc_grace_seconds`` time window.
+ For example, if the ``gc_grace_seconds`` is set to 10 days, you should run a full repair on your tables every 8-9 days to make sure your tables are repaired before the ``gc_grace_seconds`` threshold is reached.
+
+
+Additional Notes
+----------------
+You can also avoid data resurrection (and hence the requirement of running the repair every gc_grace_seconds)
+if you make sure that tombstones are generated with operations that use Consistency Level: *ALL*
+
+The operations that generate tombstones are:
+
+* DELETE operations
+* TTLs
+* INSERT/UPDATE operations that overwrite the whole composite type value(s) like *map*, *list* or *UDT*.
diff --git a/docs/kb/gossip.rst b/docs/kb/gossip.rst
--- a/docs/kb/gossip.rst
+++ b/docs/kb/gossip.rst
@@ -0,0 +1,65 @@
+Gossip in Scylla
+================
+**Topic: Internals**
+
+**Audience: Devops professionals, architects**
+
+Scylla, like Apache Cassandra, uses a type of protocol called “gossip” to exchange metadata about the identities of nodes in a cluster and whether nodes are up or down. Of course, since there is no single point of failure there can be no single registry of node state, so nodes must share information among themselves.
+
+Gossip protocols are only required in distributed systems so are probably new to most administrators. `According to Wikipedia <https://en.wikipedia.org/wiki/Gossip_protocol>`_, the ideal gossip protocol has several qualities:
+
+* Gossip involves periodic, pairwise interactions between nodes
+* Information exchanged between nodes is of bounded size.
+* The state of at least one agent changes to reflect the state of the other.
+* Reliable communication is not assumed.
+* The frequency of the interactions is low compared to typical message latencies so that the protocol costs are negligible.
+* There is some form of randomness in the peer selection.
+* Due to the replication there is an implicit redundancy of the delivered information.
+
+Individual gossip interactions in Scylla, like Apache Cassandra, are relatively infrequent and simple.
+Each node, once per second, randomly selects 1 to 3 nodes to interact with.
+
+Each node runs the gossip protocol once per second, but the gossip runs are not synchronized across the cluster.
+
+One round = three messages
+--------------------------
+One round of gossip consists of three messages. (We’ll call the node initiating the round Node A, and the randomly selected node Node B).
+
+* Node A sends: gossip_digest_syn
+* Node B sends: gossip_digest_ack
+* Node A replies: gossip_digest_ack2
+
+While the names are borrowed from TCP, gossip does not require making a new TCP connection between nodes.
+
+What are nodes gossiping about?
+-------------------------------
+Nodes exchange a small amount of information about each other. The main two data structures are heart_beat_state and application_state.
+
+A heart_beat_state contains integers for generation and “version number”. The generation is a number that grows each time the node is started, and version number is an ever-increasing integer that covers the version of the application state. ApplicationState contains data on status of components within the node (such as load) and a version number. Each node maintains a map of node IP address and node gossip metadata for all nodes in the cluster including itself.
+
+A round of gossip is designed to minimize the amount of data sent, while resolving any conflicts between the node state data on the two gossiping nodes. In the gossip_digest_syn message, Node A sends a gossip digest: a list of all its known nodes, generations, and versions. Node B compares generation and version to its known nodes, and, in the gossip_digest_ack message, sends any of its own data that differ, along with its own digest. Finally, Node A replies with any state differences between its known state and Node B’s digest.
+
+Scylla gossip implementation
+----------------------------
+Scylla gossip messages run over the Scylla messaging_service, along with all other inter-node traffic including sending mutations, and streaming of data. Scylla’s messaging_service runs on the Seastar RPC service. Seastar is the scalable software framework for multicore systems that Scylla uses. If no TCP connection is up between a pair of nodes, messaging_service will create a new one. If it is up already, messaging service will use the existing one.
+
+Gossip on multicore
+-------------------
+Each Scylla node consists of several independent shards, one per core, which operate on a shared-nothing basis and communicate without locking. Internally, the gossip component, which runs on CPU 0 only, needs to have connections forwarded from other shards. The node state data, shared by gossip, is replicated to the other shards.
+
+The gossip protocol provides important advantages especially for large clusters. Compared to “flooding” information across nodes, it can synchronize data faster, and allow for fast recovery when a new node is down or a node is returned to service. Nodes only mark other nodes as down if an actual failure is detected, but gossip quickly shares the good news of a node coming back up.
+
+References
+----------
+`Cassandra Wiki: ArchitectureGossip <https://cwiki.apache.org/confluence/display/CASSANDRA2/ArchitectureGossip>`_
+
+`Apple Inc.: Cassandra Internals — Understanding Gossip <https://www.youtube.com/watch?v=FuP1Fvrv6ZQ&list=PLqcm6qE9lgKJkxYZUOIykswDndrOItnn2&index=49>`_
+
+`Using Gossip Protocols For Failure Detection, Monitoring, Messaging And Other Good Things, by Todd Hoff <http://highscalability.com/blog/2011/11/14/using-gossip-protocols-for-failure-detection-monitoring-mess.html>`_
+
+`Gossip protocol on Wikipedia <https://en.wikipedia.org/wiki/Gossip_protocol>`_
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/ics-incremental-compaction.png b/docs/kb/ics-incremental-compaction.png
--- a/docs/kb/ics-incremental-compaction.png
+++ b/docs/kb/ics-incremental-compaction.png
null
diff --git a/docs/kb/increase-permission-cache.rst b/docs/kb/increase-permission-cache.rst
--- a/docs/kb/increase-permission-cache.rst
+++ b/docs/kb/increase-permission-cache.rst
@@ -0,0 +1,43 @@
+====================================================
+Increase Permission Cache to Avoid Non-paged Queries
+====================================================
+
+**Topic: Mitigate non-paged queries coming from connection authentications**
+
+**Audience: Scylla administrators**
+
+
+
+Issue
+-----
+
+If you create lots of roles and give them lots of permissions your nodes might spike with non-paged queries.
+
+Root Cause
+----------
+
+``permissions_cache_max_entries`` is set to 1000 by default. This setting may not be high enough for bigger deployments with lots of tables, users, and roles with permissions.
+
+
+Solution
+--------
+
+Open the scylla.yaml configuration for editing and adjust the following parameters:
+``permissions_cache_max_entries`` - increase this value to suit your needs. See the example below.
+``permissions_update_interval_in_ms``
+``permissions_validity_in_ms``
+
+Note:: ``permissions_update_interval_in_ms`` and ``permissions_validity_in_ms`` can be set to also make the authentication records come from cache instead of lookups, which generate non-paged queries
+
+
+Example
+-------
+
+Considering with ``permissions_cache_max_entries`` there is no maximum value, it's just limited by your memory.
+The cache consumes memory as it caches all records from the list of users and their associated roles (similar to a cartesian product).
+
+Every user, role, and permissions(7 types) on a per table basis are cached.
+
+If for example, you have 1 user with 1 role and 1 table, the table will have 7 permission types and 7 entries 1 * 1 * 1 * 7 = 7.
+When expanded to 5 users, 5 roles, and 10 tables this will be 5 * 5 * 10 * 7 = 1750 entries, which is above the default cache value of 1000. The entries that go over the max value (750 entries) will be non-paged queries for every new connection from the client (and clients tend to reconnect often).
+In cases like this, you may want to consider trading your memory for not stressing the entire cluster with ``auth`` queries.
\ No newline at end of file
diff --git a/docs/kb/index.rst b/docs/kb/index.rst
--- a/docs/kb/index.rst
+++ b/docs/kb/index.rst
@@ -0,0 +1,82 @@
+Knowledge Base
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+ :glob:
+
+ /kb/*
+
+.. panel-box::
+ :title: Planning and Setup
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Seed Nodes </kb/seed-nodes>` - Introduction on the purpose and role of Seed Nodes in Scylla as well as configuration tips.
+ * :doc:`Compaction </kb/compaction>` - To free up disk space and speed up reads, Scylla must do compaction operations.
+ * :doc:`DPDK mode </kb/dpdk-hardware>` - Learn to select and configure networking for DPDK mode
+ * :doc:`POSIX networking for Scylla </kb/posix>` - Scylla's POSIX mode works on all physical and virtual network devices and is useful for development work.
+ * :doc:`System Limits </kb/system-limits>` - Outlines the system limits which should be set or removed
+ * :doc:`Run Scylla as a custom user:group </kb/custom-user>` - Configure the Scylla and supporting services to run as a custom user:group.
+ * :doc:`How to Set up a Swap Space Using a File </kb/set-up-swap>` - Outlines the steps you need to take to set up a swap space.
+
+
+.. panel-box::
+ :title: Scylla under the hood
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Gossip in Scylla </kb/gossip>` - Scylla, like Cassandra, uses a type of protocol called “gossip” to exchange metadata about the identities of nodes in a cluster. Here's how it works behind the scenes.
+ * :doc:`Scylla consistency quiz for administrators </kb/quiz-administrators>` - How much do you know about NoSQL, from the administrator point of view?
+ * :doc:`Scylla Memory Usage </kb/memory-usage>` - Short explanation how Scylla manages memory
+ * :doc:`Scylla Nodes are Unresponsive </kb/unresponsive-nodes>` - How to handle swap in Scylla
+ * :doc:`CQL Query Does Not Display Entire Result Set </kb/cqlsh-more>` - What to do when a CQL query doesn't display the entire result set.
+ * :doc:`Snapshots and Disk Utilization </kb/disk-utilization>` - How snapshots affect disk utilization
+ * :doc:`Scylla Snapshots </kb/snapshots>` - What Scylla snapshots are, what they are used for, and how they get created and removed.
+ * :doc:`How does Scylla LWT Differ from Apache Cassandra ? </kb/lwt-differences>` - How does Scylla's implementation of lightweight transactions differ from Apache Cassandra?
+ * :doc:`If a query does not reveal enough results </kb/cqlsh-results>`
+ * :doc:`How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds>` - How to change the ``gc_grace_seconds`` parameter and prevent data resurrection.
+ * :doc:`How to flush old tombstones from a table </kb/tombstones-flush>` - How to remove old tombstones from SSTables.
+ * :doc:`Increase Cache to Avoid Non-paged Queries </kb/increase-permission-cache>` - How to increase the ``permissions_cache_max_entries`` setting.
+ * :doc:`How to Safely Increase the Replication Factor </kb/rf-increase>`
+ * :doc:`Facts about TTL, Compaction, and gc_grace_seconds <ttl-facts>`
+
+ **Note**: The KB article for social readers has been *removed*. Instead, please look at lessons on `Scylla University <https://university.scylladb.com/>`_ or the `Care Pet example <https://care-pet.docs.scylladb.com/master/>`_
+
+
+.. panel-box::
+ :title: Configuring and Integrating Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`NTP configuration for Scylla </kb/ntp>` - Scylla depends on an accurate system clock. Learn to configure NTP for your data store and applications.
+ * :doc:`Scylla and Spark integration </kb/scylla-and-spark-integration>` - How to run an example Spark application that uses Scylla to store data?
+ * :doc:`Map CPUs to Scylla Shards </kb/map-cpu>` - Mapping between CPUs and Scylla shards
+ * :doc:`Recreate RAID devices </kb/raid-device>` - How to recreate your RAID devices without running scylla-setup
+ * :doc:`Configure Scylla Networking with Multiple NIC/IP Combinations </kb/yaml-address>` - examples for setting the different IP addresses in scylla.yaml
+ * :doc:`Kafka Sink Connector Quickstart </using-scylla/integrations/kafka-connector>`
+ * :doc:`Kafka Sink Connector Configuration </using-scylla/integrations/sink-config>`
+
+
+.. panel-box::
+ :title: Analyzing Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Using the perf utility with Scylla </kb/use-perf>` - Using the perf utility to analyze Scylla
+ * :doc:`Debug your database with Flame Graphs </kb/flamegraph>` - How to setup and run a Flame Graph
+ * :doc:`Decoding Stack Traces </kb/decode-stack-trace>` - How to decode stack traces in Scylla Logs
+ * :doc:`Counting all rows in a table </kb/count-all-rows>` - Why counting all rows in a table often leads to a timeout
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/kb/lwt-differences.rst b/docs/kb/lwt-differences.rst
--- a/docs/kb/lwt-differences.rst
+++ b/docs/kb/lwt-differences.rst
@@ -0,0 +1,16 @@
+==================================================
+How does Scylla LWT Differ from Apache Cassandra ?
+==================================================
+
+Scylla is making an effort to be compatible with Cassandra, down to the level of limitations of the implementation.
+How is it different?
+
+* Scylla most commonly uses fewer rounds than Cassandra to complete a lightweight transaction. While Cassandra issues a separate read query to fetch the old record, scylla piggybacks the read result on the response to the prepare round.
+* Scylla will automatically use synchronous commit log write mode for all lightweight transaction writes. Before a lightweight transaction completes, scylla will ensure that the data in it has hit the device. This is done in all commitlog_sync modes.
+* Conditional statements return a result set, and unlike Cassandra, Scylla result set metadata doesn’t change from execution to execution: Scylla always returns the old version of the row, regardless of whether the condition is true or not. This ensures conditional statements work well with prepared statements.
+* For batch statement, the returned result set contains an old row for every conditional statement in the batch, in statement order. Cassandra returns results in clustering key order.
+* Unlike Cassandra, Scylla uses per-core data partitioning, so the RPC that is done to perform a transaction talks directly to the right core on a peer replica, avoiding the concurrency overhead. This is, of course, true, if Scylla’s own shard-aware driver is used - otherwise we add an extra hop to the right core at the coordinator node.
+* Scylla does not store hints for lightweight transaction writes, since this is redundant as all such writes are already present in system.paxos table.
+
+
+More on :doc:`Lightweight Transactions (LWT) </using-scylla/lwt>`
diff --git a/docs/kb/map-cpu.rst b/docs/kb/map-cpu.rst
--- a/docs/kb/map-cpu.rst
+++ b/docs/kb/map-cpu.rst
@@ -0,0 +1,42 @@
+==========================
+Map CPUs to Scylla Shards
+==========================
+
+Due to its thread-per-core architecture, many things within Scylla can be better understood when you look at it on a per-CPU basis. There are Linux tools such as ``top`` and ``perf`` that can give information about what is happening within a CPU, given a CPU number.
+
+A common mistake users make is to assume that there is a direct and predictable relationship between the Scylla Shard ID and the CPU ID, which is not true.
+
+Starting in version 3.0, Scylla ships with a script to let users know about the mapping between CPUs and Scylla Shards. For users of older versions, a copy of the script can be downloaded from the `Seastar git tree <https://raw.githubusercontent.com/scylladb/seastar/master/scripts/seastar-cpu-map.sh>`_.
+
+Examples of usage
+------------------
+
+To list the mapping of a specific shard:
+
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla -s 0
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+
+To list the mapping of all shards:
+
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+ shard: 1, cpu: 2
+ shard: 3, cpu: 4
+ shard: 2, cpu: 3
+
diff --git a/docs/kb/memory-usage.rst b/docs/kb/memory-usage.rst
--- a/docs/kb/memory-usage.rst
+++ b/docs/kb/memory-usage.rst
@@ -0,0 +1,30 @@
+Scylla Memory Usage
+===================
+
+Scylla memory usage might be larger than the data set used.
+
+For example:
+
+``The data size is 19GB, but Scylla uses 220G memory.``
+
+
+Scylla uses available memory to cache your data. Scylla knows how to dynamically manage memory for optimal performance, for example, if many clients connect to Scylla, it will evict some data from the cache to make room for these connections, when the connection count drops again, this memory is returned to the cache.
+
+To limit the memory usage you can start scylla with ``--memory`` parameter.
+Alternatively, you can specify the amount of memory ScyllaDB should leave to the OS with ``--reserve-memory`` parameter. Keep in mind that the amount of memory left to the operating system needs to suffice external scylla modules, such as ``scylla-jmx``, which runs on top of JVM.
+
+On Ubuntu, edit the ``/etc/default/scylla-server``.
+
+On Red Hat / CentOS, edit the ``/etc/sysconfig/scylla-server``.
+
+
+
+For example:
+
+.. code-block:: yaml
+
+ SCYLLA_ARGS="--log-to-syslog 1 --log-to-stdout 0 --default-log-level info --collectd-address=127.0.0.1:25826 --collectd=1 --collectd-poll-period 3000 --network-stack posix --memory 2G --reserve-memory 2G
+
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/ntp.rst b/docs/kb/ntp.rst
--- a/docs/kb/ntp.rst
+++ b/docs/kb/ntp.rst
@@ -0,0 +1,148 @@
+NTP Configuration for Scylla
+============================
+**Topic: System administration**
+
+**Learn: How to configure time synchronization for Scylla**
+
+**Audience: Scylla and Apache Cassandra administrators**
+
+Apache Cassandra and Scylla depend on an accurate system clock. Kyle Kingsbury,
+author of the ``jepsen`` distributed systems testing tool,
+`writes <https://aphyr.com/posts/299-the-trouble-with-timestamps>`_,
+
+ Apache Cassandra uses wall-clock timestamps provided by the server, or
+ optionally by the client, to order writes. It makes several
+ guarantees about the monotonicity of writes and reads given
+ timestamps. For instance, Cassandra guarantees most of the time that
+ if you write successfully to a quorum of nodes, any subsequent read
+ from a quorum of nodes will see that write or one with a greater
+ timestamp.
+
+So servers need to keep their time in sync. Not a hard problem, since we
+all have NTP on our Linux systems, right? Not quite. The way that NTP
+ships out of the box is fine for a stand-alone server, but can be a
+problem for a distributed data store.
+
+You did WHAT in the Pool?
+-------------------------
+
+The default NTP configuration that comes with a typical Linux system
+uses “NTP pools”, lists of publicly available time servers contributed
+by public-minded Internet timekeeping system administrators. The pools
+are a valuable service, but in order to spare the NTP traffic load on
+any given server, they’re managed with DNS round robin. One client that
+tries to resolve the hostname ``0.pool.ntp.org`` will get a different
+result from another client.
+
+As Viliam Holub points out in a two-part series -- `part
+1 <https://blog.logentries.com/2014/03/synchronizing-clocks-in-a-cassandra-cluster-pt-1-the-problem/>`__,
+`part
+2 <https://blog.logentries.com/2014/03/synchronizing-clocks-in-a-cassandra-cluster-pt-2-solutions/>`__
+-- if Apache Cassandra nodes in a cluster are independently obtaining their
+time from random pool servers out on the Internet, the chances that two
+nodes can have widely (by NTP standards) differing time is high. For
+example, if a cluster has 10 nodes, 50% of the time some pair of nodes
+will have time that differs by more than 10.9ms. The problem only grows
+as more nodes are added.
+
+The solution is to be able to take that ntp.conf file that came with
+your Linux distribution, and take the default “pool” servers out and put
+your data center’s own NTP servers in.
+
+Instead of lines that looks something like:
+
+::
+
+ server 0.fedora.pool.ntp.org iburst
+ server 1.fedora.pool.ntp.org iburst
+
+Or
+
+::
+
+ server 0.debian.pool.ntp.org iburst
+ server 1.debian.pool.ntp.org iburst
+
+use your own servers. So ntp.conf will have “server” lines pointing to
+your own NTP servers, and look more like:
+
+::
+
+ # begin ntp.conf
+
+ # Store clock drift -- see ntp.conf(5)
+ driftfile /var/lib/ntp/drift
+
+ # Restrict all access by default
+ restrict default nomodify notrap nopeer noquery
+
+ # Allow localhost access and LAN management
+ restrict 127.0.0.1
+ restrict ::1
+ restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap
+
+ # Use our company’s NTP servers only
+ server 0.ntp.example.com iburst
+ server 1.ntp.example.com iburst
+ server 2.ntp.example.com iburst
+
+ # End ntp.conf
+
+The same ntp.conf can be deployed to all the servers in your data
+center. Not just Apache Cassandra nodes, but the application servers that use
+them. It’s much more important for the time to be in sync throughout the
+cluster than for any node to match some random machine out on the
+Internet. It’s also helpful to keep the data store time the same as the
+application server’s time, for ease in troubleshooting and matching up
+log entries.
+
+Dedicated NTP appliances are available, and might be a good choice for
+large sites. Otherwise, any standard Linux system should make a good NTP
+server.
+
+On the NTP servers, you can go ahead and use the “pool.ntp.org” server
+lines that shipped with your Linux distribution if you don’t have a
+known good time server. But a good hosting provider or business-class
+ISP probably has NTP servers that are close to you on the network, and
+that would be better choices to replace the pool entries.
+
+Your NTP servers should peer with each other:
+
+::
+
+ peer 0.ntp.example.com prefer
+ peer 1.ntp.example.com
+ peer 2.ntp.example.com
+
+Almost done.
+
+Pass the Fudge?
+---------------
+
+What happens when the network goes down? In most cases, NTP should just
+work. Your NTP servers will establish a new consensus time among
+themselves. Old-school NTP documentation had “fudge” lines to let the
+NTP server rely on the local system clock if the network connection
+failed. On modern versions of NTP, the “fudge” functionality has been
+replaced with `Orphan
+mode <http://support.ntp.org/bin/view/Support/OrphanMode>`__.
+
+Add an “orphan” line to ntp.conf on each NTP server:
+
+::
+
+ tos orphan 9
+
+And the NTP servers will do the right thing and stay synchronized among
+themselves if there’s a problem reaching the servers on the outside.
+
+That’s all it takes. One relatively simple system administration project
+can save a bunch of troubleshooting grief later on. Once your NTP
+servers are working, have a look at the `instructions for joining the
+NTP pool <http://www.pool.ntp.org/join.html>`__ yourself, so that you
+can help share the correct time with others
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/perf-top.png b/docs/kb/perf-top.png
--- a/docs/kb/perf-top.png
+++ b/docs/kb/perf-top.png
null
diff --git a/docs/kb/posix.rst b/docs/kb/posix.rst
--- a/docs/kb/posix.rst
+++ b/docs/kb/posix.rst
@@ -0,0 +1,55 @@
+POSIX networking for Scylla
+===========================
+**Topic: Planning and setup**
+
+**Learn: How to configure POSIX networking for Scylla**
+
+**Audience: Developers, devops, integration testers**
+
+The Seastar framework used in Scylla can support two networking modes.
+For high-performance production workloads, use the Data Plane
+Development Kit (DPDK) for maximum performance on specific modern
+network hardware.
+
+For ease of development, you can also use POSIX mode, which works on all
+physical and virtual network devices supported by your operating system.
+
+Kernel Configuration
+--------------------
+
+The Linux “transparent hugepages” feature is recommended, but not
+required, in POSIX mode to minimize overhead on memory allocations. The
+value of ``/sys/kernel/mm/transparent_hugepage/enabled`` should be
+``always`` or ``madvise``. See your Linux distribution's documentation
+for instructions on how to enable transparent hugepages.
+
+Firewall Configuration
+----------------------
+
+For a single node, the firewall will need to be set up to allow TCP on
+the following :ref:`ports <cqlsh-networking>`.
+
+Scylla Configuration
+--------------------
+
+POSIX mode is the default, in ``/etc/sysconfig/scylla-server``. Check
+that ``NETWORK_MODE`` is set to ``posix``.
+
+::
+
+ # choose following mode: virtio, dpdk, posix
+ NETWORK_MODE=posix.
+
+The ``ETHDRV`` option is ignored in POSIX mode.
+
+More Information
+----------------
+
+`Cassandra: configuring firewall port
+access <http://docs.datastax.com/en//cassandra/2.0/cassandra/security/secureFireWall_r.html>`__
+
+`How to use, monitor, and disable transparent hugepages in Red Hat
+Enterprise Linux 6 <https://access.redhat.com/solutions/46111>`__
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/quiz-administrators.rst b/docs/kb/quiz-administrators.rst
--- a/docs/kb/quiz-administrators.rst
+++ b/docs/kb/quiz-administrators.rst
@@ -0,0 +1,34 @@
+Scylla consistency quiz for administrators
+==========================================
+**Topic: Architecture and development**
+
+**Learn: Understanding consistency in Scylla: a quiz**
+
+**Audience: Scylla administrators**
+
+Q: When you run ``nodetool decommission`` to remove a node…
+
+1. Will the token range the node had be relocated to other nodes?
+ What about vnodes?
+
+2. When and how will we know the “decommission” operation is finished?
+
+A1. Yes. The node enters the state “STATE\_LEAVING” while streaming its
+data to other nodes. Then it is in “STATE\_LEFT” when the data has been
+streamed.
+
+A2. Use ``nodetool netstats`` to check the state of a node.
+
+Q: Let's say I have a 16 node cluster using Network Topology Strategy
+across 2 data centers. The replication factor is TWO in each datacenter
+(DC1: 2, DC2: 2). If I write using a LOCAL\_QUORUM, I will write the
+data to 4 nodes (2 in each data center) but when will the
+acknowledgement happen?
+
+
+A: The acknowledgment will be sent to the user when two **local** replicas respond.
+In this case, floor(local_RF/2 +1) = 2 , so LOCAL\_QUORUM is equal to RF per DC, which is why RF of 3 is usually better.
+
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/raid-device.rst b/docs/kb/raid-device.rst
--- a/docs/kb/raid-device.rst
+++ b/docs/kb/raid-device.rst
@@ -0,0 +1,14 @@
+=====================
+Recreate RAID devices
+=====================
+
+Scylla creates a RAID device on all storage devices assigned to it as part of Scylla setup. However, there are situations in which we want to redo just this step, without invoking the entire setup phase again. One example of such a situation is when Scylla is used in Clouds with ephemeral storage. After a hard stop, the storage devices will be reset and the previous setup will be destroyed.
+To recreate your RAID devices, run this script:
+
+.. code-block:: shell
+
+ scylla_raid_setup --raiddev /dev/md0 --disks <comma-separated list of disks>
+
+After this step the storage will be mounted, formatted, and /var/lib/scylla created.
+
+
diff --git a/docs/kb/rf-increase.rst b/docs/kb/rf-increase.rst
--- a/docs/kb/rf-increase.rst
+++ b/docs/kb/rf-increase.rst
@@ -0,0 +1,50 @@
+=======================================================
+How to Safely Increase the Replication Factor
+=======================================================
+
+
+**Topic: What can happen when you increase RF**
+
+
+**Audience: Scylla administrators**
+
+
+Issue
+-----
+
+When a Replication Factor (RF) is increased, using the :ref:`ALTER KEYSPACE <alter-keyspace-statement>` command, the data consistency is effectively dropped
+by the difference of the RF_new value and the RF_old value for all pre-existing data.
+Consistency will only be restored after running a repair.
+
+Resolution
+----------
+
+When one increases an RF, one should consider that the pre-existing data will **not be streamed** to new replicas (a common misconception).
+
+As a result, in order to make sure that you can keep on reading the old data with the same level of consistency, increase the read Consistency Level (CL) according to the following formula:
+
+``CL_new = CL_old + RF_new - RF_old``
+
+After you run a repair, you can decrease the CL. If RF has only been changed in a particular Data Center (DC) only the nodes in that DC have to be repaired.
+
+Example
+=======
+
+In this example your five node cluster RF is 3 and your CL is TWO. You want to increase your RF from 3 to 5.
+
+#. Increase the read CL by a RF_new - RF_old value.
+ Following the example the RF_new is 5 and the RF_old is 3 so, 5-3 =2. You need to increase the CL by 2.
+ As the CL is currently TWO, increasing it more would be QUORUM, but QUORUM would not be high enough. For now, increase it to ALL.
+#. Change the RF to RF_new. In this example, you would increase the RF to 5.
+#. Repair all tables of the corresponding keyspace. If RF has only been changed in a particular Data Center (DC), only the DC nodes have to be repaired.
+#. Restore the reads CL to the originally intended value. For this example, QUORUM.
+
+
+If you do not follow the procedure above you may start reading stale or null data after increasing the RF.
+
+More Information
+----------------
+
+* :doc:`Fault Tolerance </architecture/architecture-fault-tolerance/>`
+* :ref:`Set the RF (first time) <create-keyspace-statement>`
+* :ref:`Change the RF (increase or decrease) <alter-keyspace-statement>`
diff --git a/docs/kb/scylla-and-spark-integration.rst b/docs/kb/scylla-and-spark-integration.rst
--- a/docs/kb/scylla-and-spark-integration.rst
+++ b/docs/kb/scylla-and-spark-integration.rst
@@ -0,0 +1,359 @@
+Scylla and Spark integration
+============================
+
+
+Simple Scylla-Spark integration example
+---------------------------------------
+
+This is an example of how to create a very simple Spark application that
+uses Scylla to store its data. The application is going to read people's
+names and ages from one table and write the names of the adults to
+another one. It also will show the number of adults and all people in
+the database.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- Scylla
+- sbt
+
+Prepare Scylla
+~~~~~~~~~~~~~~
+
+Firstly, we need to create keyspace and tables in which data processed
+by the example application will be stored.
+
+Launch Scylla and connect to it using cqlsh. The following commands will
+create a new keyspace for our tests and make it the current one.
+
+::
+
+ CREATE KEYSPACE spark_example WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1};
+ USE spark_example;
+
+Then, tables both for input and output data need to be created:
+
+::
+
+ CREATE TABLE persons (name TEXT PRIMARY KEY, age INT);
+ CREATE TABLE adults (name TEXT PRIMARY KEY);
+
+Lastly, the database needs to contain some input data for our
+application to process:
+
+::
+
+ INSERT INTO persons (name, age) VALUES ('Anne', 34);
+ INSERT INTO persons (name, age) VALUES ('John', 47);
+ INSERT INTO persons (name, age) VALUES ('Elisabeth', 89);
+ INSERT INTO persons (name, age) VALUES ('George', 52);
+ INSERT INTO persons (name, age) VALUES ('Amy', 17);
+ INSERT INTO persons (name, age) VALUES ('Jack', 16);
+ INSERT INTO persons (name, age) VALUES ('Treebeard', 36421);
+
+Prepare the application
+~~~~~~~~~~~~~~~~~~~~~~~
+
+With a database containing all the necessary tables and data, it is now
+time to write our example application. Create a directory
+``scylla-spark-example``, which will contain all source code and build
+configuration.
+
+First, very important file is ``build.sbt``, which should be created in
+the project main directory. It contains all the application metadata,
+including name, version, and dependencies.
+
+::
+
+ name := "scylla-spark-example-simple"
+ version := "1.0"
+ scalaVersion := "2.10.5"
+
+ libraryDependencies ++= Seq(
+ "com.datastax.spark" %% "spark-cassandra-connector" % "1.5.0-M1",
+ "org.apache.spark" %% "spark-catalyst" % "1.5.0" % "provided"
+ )
+
+Then, we need to enable ``sbt-assembly`` plugin. Create directory
+``project`` and create file ``plugins.sbt`` with the following content:
+
+::
+
+ addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.0")
+
+The steps above should cover all build configuration, what is left is
+the actual logic of the application. Create file
+``src/main/scala/ScyllaSparkExampleSimple.scala``:
+
+.. code:: scala
+
+ import org.apache.spark.{SparkContext,SparkConf}
+ import com.datastax.spark.connector._
+
+ object ScyllaSparkExampleSimple {
+ def main(args: Array[String]): Unit = {
+ val sc = new SparkContext(new SparkConf())
+
+ val persons = sc.cassandraTable("spark_example", "persons")
+
+ val adults = persons.filter(_.getInt("age") >= 18).map(n => Tuple1(n.getString("name")))
+ adults.saveToCassandra("spark_example", "adults")
+
+ val out = s"Adults: %d\nTotal: %d\n".format(adults.count(), persons.count())
+ println(out)
+ }
+ }
+
+Since we don't want to hardcode in our application any information about
+Scylla or Spark we will also need an additional configuration file
+``spark-scylla.conf``.
+
+::
+
+ spark.master local
+ spark.cassandra.connection.host 127.0.0.1
+
+Now it is time to build the application and create a self-containing jar
+file that we will be able to send to Spark. To do that, execute the command:
+
+::
+
+ sbt assembly
+
+It will download all necessary dependencies, build our example, and
+create an output jar file in
+``target/scala-2.10/scylla-spark-example-simple-assembly-1.0.jar``.
+
+Download and run Spark
+~~~~~~~~~~~~~~~~~~~~~~
+
+The next step is to get Spark running. Pre-built binaries can be
+downloaded from `this <http://spark.apache.org/downloads.html>`__
+website. Make sure to choose release 1.5.0. Since we are going to use it
+with Scylla Hadoop version doesn't matter.
+
+Once the download has finished, unpack the archive and in its root
+directory, execute the following command to start Spark Master:
+
+::
+
+ ./sbin/start-master.sh -h localhost
+
+Spark Web UI should now be available at http://localhost:8080. The Spark
+URL used to connect its workers is ``spark://localhost:7077``.
+
+With the master running, the only thing left to have minimal Spark
+deployment is to start a worker. This can be done with the following
+command:
+
+::
+
+ ./sbin/start-slave.sh spark://localhost:7077
+
+Run application
+~~~~~~~~~~~~~~~
+
+The application is built, Spark is up, and Scylla has all the necessary
+tables created and contains the input data for our example. This means
+that we are ready to run the application. Make sure that Scylla is
+running and execute (still in the Spark directory) the following
+command):
+
+::
+
+ ./bin/spark-submit --properties-file /path/to/scylla-spark-example/spark-scylla.conf \
+ --class ScyllaSparkExampleSimple /path/to/scylla-spark-example/target/scala-2.10/scylla-spark-example-simple-assembly-1.0.jar
+
+``spark-submit`` will output some logs and debug information, but among
+them, there should be a message from the application:
+
+::
+
+ Adults: 5
+ Total: 7
+
+You can also connect to Scylla with cqlsh, and using the following query,
+see the results of our example in the database.
+
+::
+
+ SELECT * FROM spark_example.adults;
+
+Expected output:
+
+::
+
+ name
+ -----------
+ Treebeard
+ Elisabeth
+ George
+ John
+ Anne
+
+Based on
+http://www.planetcassandra.org/getting-started-with-apache-spark-and-cassandra/
+and http://koeninger.github.io/spark-cassandra-example/#1.
+
+RoadTrip example
+----------------
+
+This is a short guide explaining how to run a Spark example application
+available `here <https://github.com/jsebrien/spark-tests>`__ with
+Scylla.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- Scylla
+- Maven
+- Git
+
+Get the source code
+~~~~~~~~~~~~~~~~~~~
+
+You can get the source code of this example by cloning the following
+repository:
+
+::
+
+ https://github.com/jsebrien/spark-tests
+
+Disable Apache Cassandra
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+spark-tests are configured to launch Cassandra, which is not what we want
+to achieve here. The following patch disables Cassandra. It can be
+applied, for example, using ``git apply --ignore-whitespace -``.
+
+.. code:: diff
+
+ diff --git a/src/main/java/blog/hashmade/spark/util/CassandraUtil.java b/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ index 37bbc2e..bfe5517 100644
+ --- a/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ +++ b/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ @@ -14,7 +14,7 @@ public final class CassandraUtil {
+ }
+
+ static Session startCassandra() throws Exception {
+ - EmbeddedCassandraServerHelper.startEmbeddedCassandra();
+ + //EmbeddedCassandraServerHelper.startEmbeddedCassandra();
+ Thread.sleep(EMBEDDED_CASSANDRA_SERVER_WAITING_TIME);
+ Cluster cluster = new Cluster.Builder().addContactPoints("localhost")
+ .withPort(9142).build();
+
+Update connector
+~~~~~~~~~~~~~~~~
+
+spark-tests use Spark Cassandra Connector in version 1.1.0 which is too
+old for our purposes. Before 1.3.0 the connector used to use Thrift as
+well CQL and that won't work with Scylla. Updating the example isn't
+very complicated and can be accomplished by applying the following
+patch:
+
+.. code:: diff
+
+ diff --git a/pom.xml b/pom.xml
+ index 673e22b..1245ffc 100644
+ --- a/pom.xml
+ +++ b/pom.xml
+ @@ -142,7 +142,7 @@
+ <dependency>
+ <groupId>org.apache.spark</groupId>
+ <artifactId>spark-core_2.10</artifactId>
+ - <version>1.1.0</version>
+ + <version>1.3.0</version>
+ <exclusions>
+ <exclusion>
+ <groupId>com.google.guava</groupId>
+ @@ -157,7 +157,7 @@
+ <dependency>
+ <groupId>org.apache.spark</groupId>
+ <artifactId>spark-streaming_2.10</artifactId>
+ - <version>1.1.0</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.cassandraunit</groupId>
+ @@ -173,18 +173,18 @@
+ <dependency>
+ <groupId>com.datastax.cassandra</groupId>
+ <artifactId>cassandra-driver-core</artifactId>
+ - <version>2.1.2</version>
+ + <version>2.1.7.1</version>
+ </dependency>
+ <!-- Datastax -->
+ <dependency>
+ <groupId>com.datastax.spark</groupId>
+ <artifactId>spark-cassandra-connector_2.10</artifactId>
+ - <version>1.1.0-beta2</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>com.datastax.spark</groupId>
+ <artifactId>spark-cassandra-connector-java_2.10</artifactId>
+ - <version>1.1.0-beta2</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>net.sf.supercsv</groupId>
+ diff --git a/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java b/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ index 1027e42..190eb3d 100644
+ --- a/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ +++ b/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ @@ -43,8 +43,7 @@ public class DatastaxSparkTest {
+ .setAppName("DatastaxTests")
+ .set("spark.executor.memory", "1g")
+ .set("spark.cassandra.connection.host", "localhost")
+ - .set("spark.cassandra.connection.native.port", "9142")
+ - .set("spark.cassandra.connection.rpc.port", "9171");
+ + .set("spark.cassandra.connection.port", "9142");
+ SparkContext ctx = new SparkContext(conf);
+ SparkContextJavaFunctions functions = CassandraJavaUtil.javaFunctions(ctx);
+ CassandraJavaRDD<CassandraRow> rdd = functions.cassandraTable("roadtrips", "roadtrip");
+
+Build the example
+~~~~~~~~~~~~~~~~~
+
+The example can be built with Maven:
+
+::
+
+ mvn compile
+
+Start Scylla
+~~~~~~~~~~~~
+
+The application we are trying to run will try to connect with Scylla
+using custom port 9142. That's why when starting Scylla, an additional
+flag is needed to make sure that's the port it listens on
+(alternatively, you can change all occurrences of 9142 to 9042 in the
+example source code).
+
+::
+
+ scylla --native-transport-port=9142
+
+Run the application
+~~~~~~~~~~~~~~~~~~~
+
+With the example compiled and Scylla running all that is left to be done
+is to actually run the application:
+
+::
+
+ mvn exec:java
+
+Scylla limitations
+------------------
+
+- Scylla needs Spark Cassandra Connector 1.3.0 or later.
+- Scylla doesn't populate ``system.size_estimates``, and therefore the
+ connector won't be able to perform automatic split sizing optimally.
+
+For more compatibility information check `Scylla status <http://www.scylladb.com/technology/status/>`_
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/scylla-limits-systemd.rst b/docs/kb/scylla-limits-systemd.rst
--- a/docs/kb/scylla-limits-systemd.rst
+++ b/docs/kb/scylla-limits-systemd.rst
@@ -0,0 +1,94 @@
+============================================
+Increase Scylla resource limits over systemd
+============================================
+
+**Topic: Increasing resource limits when Scylla runs and is managed via systemd**
+
+**Audience: Scylla administrators**
+
+
+
+Issue
+-----
+
+Updates to ``/etc/security/limits.d/scylla.conf`` do not have any effect. After a cluster rolling restart is completed, the Scylla limits listed under ``/proc/<PID>/limits`` are still the same or lower than what has been configured.
+
+Root Cause
+----------
+
+When running under systemd, Scylla enforces the **LimitNOFILE** and **LimitNPROC** values under ``/lib/systemd/system/scylla-server.service``, where:
+
+**LimitNOFILE** - Maximum number of file descriptors allowed to be opened simultaneously (defaults to 800000)
+
+**LimitNPROC** - Maximum number of processes allowed to run in parallel (defaults to 8096)
+
+Even though Scylla's provided defaults are suitable for most workloads, there may be situations on which these values may need to be overriden.
+
+Before you start
+----------------
+
+The Linux kernel imposes an upper limit on the maximum number of file-handles that a process may allocate, which takes precedence over systemd. Such limit may be persistently increased by tuning the ``fs.nr_open`` parameter in the ``/etc/sysctl.conf`` file.
+
+The ``fs.nr_open`` parameter default value is 1048576 (1024*1024) and it must be increased whenever it is required to overcome such limit.
+
+As a rule of thumb, always ensure that the value of ``fs.nr_open`` is **equal or greater than** the maximum number of file-handles that Scylla may be able to consume.
+
+1. To check the value of ``fs.nr_open`` run:
+
+.. code-block:: shell
+
+ sysctl fs.nr_open
+ fs.nr_open = 1048576
+
+2. Edit the file ``/etc/sysctl.conf`` as root, and increase the value of ``fs.nr_open``:
+
+.. code-block:: shell
+
+ sudo vi /etc/sysctl.conf
+ fs.nr_open=5000000
+
+3. Save the changes and apply the new setting to the running configuration:
+
+.. code-block:: shell
+
+ sudo sysctl -p
+
+
+
+Solution
+--------
+
+1. To override Scylla limits on systemd, run:
+
+.. code-block:: shell
+
+ sudo systemctl edit scylla-server.service
+
+2. Within the opened text editor, add the following lines and adjust the parameters as needed, e.g.:
+
+**Warning**: Avoid setting the value of such fields to `Infinity` as this can lead to unpredictable behaviors. When adjusting the value of **LimitNOFILE** always set it to a value which is **equal or lower than** the value of ``fs.nr_open``
+
+.. code-block:: shell
+
+ [Service]
+ LimitNOFILE=5000000
+
+3. Restart Scylla:
+
+.. code-block:: shell
+
+ sudo systemctl restart scylla-server.service
+
+This will create a configuration file named ``override.conf`` under the ``/etc/systemd/system/scylla-server.service.d`` folder. Whenever editing this file by hand manually, remember to run ``sudo systemctl daemon-reload`` before restarting Scylla, so that systemd reloads the changes.
+
+4. To check the updated limits allowed by the Scylla process run:
+
+.. code-block:: shell
+
+ cat /proc/$(pidof scylla)/limits
+
+References
+----------
+
+* `The Linux Kernel Documentation for /proc/sys/fs/*` <https://www.kernel.org/doc/Documentation/sysctl/fs.txt>
+* `systemd.exec(5) manpage`
diff --git a/docs/kb/seed-nodes.rst b/docs/kb/seed-nodes.rst
--- a/docs/kb/seed-nodes.rst
+++ b/docs/kb/seed-nodes.rst
@@ -0,0 +1,48 @@
+=================
+Scylla Seed Nodes
+=================
+
+**Topic: Scylla Seed Nodes Overview**
+
+**Learn: What a seed node is, and how they should be used in a Scylla Cluster**
+
+**Audience: Scylla Administrators**
+
+
+What is the Function of a Seed Node in Scylla?
+----------------------------------------------
+
+.. note::
+ Seed nodes function was changed in Scylla Open Source 4.3 and Scylla Enterprise 2021.1; if you are running an older version, see :ref:`Older Version Of Scylla <seeds-older-versions>`.
+
+A Scylla seed node is a node specified with the ``seeds`` configuration parameter in ``scylla.yaml``. It is used by new node joining as the first contact point.
+It allows nodes to discover the cluster ring topology on startup (when joining the cluster). This means that any time a node is joining the cluster, it needs to learn the cluster ring topology, meaning:
+
+- What are the IPs of the nodes in the cluster are
+- Which token ranges are available
+- Which nodes will own which tokens when a new node joins the cluster
+
+**Once the nodes have joined the clutser, seed node has no function.**
+
+The first node in a new cluster needs to be a seed node.
+
+.. _seeds-older-versions:
+
+Older Version Of Scylla
+----------------------------
+
+In Scylla releases older than Scylla Open Source 4.3 and Scylla Enterprise 2021.1, seed node has one more function: it assists with :doc:`gossip </kb/gossip>` convergence.
+Gossiping with other nodes ensures that any update to the cluster is propagated across the cluster. This includes detecting and alerting whenever a node goes down, comes back, or is removed from the cluster.
+
+This functions was removed, as described in `Seedless NoSQL: Getting Rid of Seed Nodes in ScyllaDB <https://www.scylladb.com/2020/09/22/seedless-nosql-getting-rid-of-seed-nodes-in-scylla/>`_.
+
+If you run an older Scylla release, we recommend upgrading to version 4.3 (Scylla Open Source) or 2021.1 (Scylla Enterprise) or later. If you choose to run an older version, it is good practice to follow these guidelines:
+
+* The first node in a new cluster needs to be a seed node.
+* Ensure that all nodes in the cluster have the same seed nodes listed in each node's scylla.yaml.
+* To maintain resiliency of the cluster, it is recommended to have more than one seed node in the cluster.
+* If you have more than one seed in a DC with multiple racks (or availability zones), make sure to put your seeds in different racks.
+* You must have at least one node that is not a seed node. You cannot create a cluster where all nodes are seed nodes.
+* You should have more than one seed node.
+
+
diff --git a/docs/kb/set-up-swap.rst b/docs/kb/set-up-swap.rst
--- a/docs/kb/set-up-swap.rst
+++ b/docs/kb/set-up-swap.rst
@@ -0,0 +1,120 @@
+===========================
+How to Set up a Swap Space
+===========================
+
+.. note:: It is recommended to run the ``scylla_setup`` script to setup your swap space. ``scylla_setup`` runs a script called ``scylla_swap_setup``.
+ You can also run the script using the `Set Up Swap Space with a Script`_ procedure below. If this doesn't work use the procedure below to `Set Up Swap Space with a File`_.
+
+Set Up Swap Space with a Script
+-------------------------------
+
+The help for the script can be accessed by ``scylla_swap_setup --help``.
+
+.. code-block:: shell
+
+ scylla_swap_setup --help
+ usage: scylla_swap_setup [-h] [--swap-directory SWAP_DIRECTORY] [--swap-size SWAP_SIZE]
+
+ Configure swap for Scylla.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --swap-directory SWAP_DIRECTORY
+ specify swapfile directory
+ --swap-size SWAP_SIZE
+ specify swapfile size in GB
+
+
+**Procedure**
+
+#. Run the script setup command in a terminal specifying the target directory and size.
+
+.. code-block:: shell
+
+ sudo scylla_swap_setup --swap-directory /tmp/swp --swap-size SWAP_SIZE 500
+
+
+Set Up Swap Space with a File
+-----------------------------
+
+Use this procedure if the `Set Up Swap Space with a Script`_ procedure did not give you the desired results.
+
+This tutorial is suitable for any Linux distribution.
+
+This procedure adds 6GB of swap to your server. If you want to add a different amount, replace ``6G`` with the size you require.
+
+Keep in mind that
+
+``swap`` size should be set to either ``total_mem``/3 or 16GB - lower of the two.
+
+``total_mem`` is the total size of the nodes memory.
+
+For example:
+
+* If the node ``total_mem`` is 18GB ``swap`` size should be set to 6GB.
+
+* If the node ``total_mem`` is 240GB ``swap`` size should be set to 16GB.
+
+**Procedure**
+
+#. Create a file that will be used for swap.
+
+ .. code-block:: shell
+
+ sudo fallocate -l 6G /swapfile
+
+#. Change the permissions setting on the file so that only the root user is be able to write and read the swap file.
+
+ .. code-block:: shell
+
+ sudo chmod 600 /swapfile
+
+#. Run the Use *mkswap* utility to set up the file as Linux swap area.
+
+ .. code-block:: shell
+
+ sudo mkswap /swapfile
+
+#. Enable the swap.
+
+ .. code-block:: shell
+
+ sudo swapon /swapfile
+
+#. To make the change sustainable, open the ``/etc/fstab`` file and append the following:
+
+ .. code-block:: shell
+
+ /swapfile swap swap defaults 0 0
+
+#. Verify that swap is active.
+
+ .. code-block:: shell
+
+ sudo swapon --show
+ NAME TYPE SIZE USED PRIO
+ /swapfile file 6024M 507.4M -1
+
+Remove a Swap File
+-------------------
+
+#. Deactivate Swap.
+
+ .. code-block:: none
+
+ sudo swapoff -v /swapfile
+
+#. Remove the sap file entry by editing the ``/etc/fstab`` file and removing ``/swapfile swap swap defaults 0 0``.
+
+#. Delete the swap file.
+
+ .. code-block:: none
+
+ sudo rm /swapfile
+
+
+Additional Information
+----------------------
+
+* `Configure swap for Scylla <https://github.com/scylladb/scylla/blob/master/dist/common/scripts/scylla_swap_setup>`_
+* :doc:`Setup Scripts </getting-started/system-configuration>`.
diff --git a/docs/kb/snapshots.rst b/docs/kb/snapshots.rst
--- a/docs/kb/snapshots.rst
+++ b/docs/kb/snapshots.rst
@@ -0,0 +1,101 @@
+================
+Scylla Snapshots
+================
+
+.. your title should be something customers will search for.
+
+**Topic: snapshots**
+
+.. Give a subtopic for the title (User Management, Security, Drivers, Automation, Optimization, Schema management, Data Modeling, etc.)
+
+**Learn: What are Scylla snapshots? What are they used for? How do they get created and removed?**
+
+
+**Audience: Scylla administrators**
+
+.. Choose (Application Developer, Scylla Administrator, Internal, All)
+
+Synopsis
+--------
+
+Snapshots in Scylla are an essential part of the :doc:`backup and restore mechanism </operating-scylla/procedures/backup-restore/index>`. Whereas in other databases a backup starts with creating a copy of a data file (cold backup, hot backup, shadow copy backup), in Scylla the process starts with creating a table or keyspace snapshot. The snapshots are created either automatically (this is described further in this article) or by invoking the :doc:`nodetool snapshot </operating-scylla/nodetool-commands/snapshot>` command.
+To prevent any issues with restoring your data, the backup strategy must include saving copies of the snapshots on a secondary storage. This makes sure the snapshot is available to restore if the primary storage fails.
+
+.. note:: If you come from RDBMS background you should not confuse snapshots with the notion of materialized views (as they are sometimes called snapshots in that area of technology). With Scylla, snapshots are `hard links <https://en.wikipedia.org/wiki/Hard_link>`_ to data files. :doc:`Materialized views </using-scylla/materialized-views>` do exist in Scylla but they are not called snapshots.
+
+
+How Snapshots Work
+------------------
+
+Scylla, like Cassandra, requires `Unix-like storage <https://en.wikipedia.org/wiki/Unix_filesystem?>`_ (such is also a file system supported by Linux). As mentioned above, snapshots are hard links to SSTables on disk. It is important to understand that SSTables are immutable and as such are not re-written in the same file. When data in database changes and data is written to disk, it is written as a new file. The new files are consolidated following compaction, which merges table’s data into one or more SSTable files (depending on the compaction strategy).
+
+If snapshots (hard links) were created to existing SSTables on disk they are preserved even if table data is eventually stored in one or more of the new SSTables. The :doc:`compaction process </getting-started/compaction>` removes files in the data directory, but the snapshot hard links **will still** be pointing to the **old files**. Only after all of the pointers are removed, the actual file is removed. If even one pointer exists, the file will remain. Therefore, even as the database is moving on, once the snapshot hard links are created, the content of the data files can be copied off to another storage and serve as the foundation for a table, keyspace, or entire database restore (on that node, as this backup and restore process is node specific).
+
+Apart from *planned backup* procedure described above, and as a safeguard from *accidental* loss of data, the Scylla database includes an optional creation of an automatic snapshot every time a table is dropped or truncated. As dropping a keyspace involves dropping tables within that keyspace, these actions will invoke auto snapshots as well. This option is enabled out of the box and is controlled by the auto_snapshot flag in the ``/etc/scylla/scylla.yaml`` configuration file. Note that a keyspace cannot be truncated. It can only be dropped. A table, on the other hand, can be either truncated or dropped. The data in a table can also be deleted, which is different from being truncated.
+
+The default setting for the ``auto_snapshot`` flag in ``/etc/scylla/scylla.yaml`` file is ``true``. It is **not** recommended to set it to ``false``, unless there is a good backup and recovery strategy in place.
+
+Snapshot Creation
+-----------------
+
+Snapshots **are created** when:
+
+* ``nodetool snapshot <keyspace_name>`` runs as this creates snapshots for all tables in the keyspace.
+* ``nodetool snapshot <keyspace_name>.<table_name>`` runs as this creates snapshots for a specific table
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the table is dropped (as in ``DROP TABLE <keyspace_name>.<table_name>`` )
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the table is truncated (as in ``TRUNCATE TABLE <keyspace_name>.<table_name>`` )
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the keyspace is dropped (as in ``DROP KEYSPACE <keyspace_name>`` ) - which is the equivalent to dropping all tables in the keyspace and also dropping the keyspace as well.
+
+Snapshots **are not created** when:
+
+* Data in the table is deleted, as opposed to truncated.
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``false`` and the table is dropped or truncated.
+
+
+List Current Snapshots
+-----------------------
+
+Snapshot information for tables or keyspaces which are present in the database at the time of invoking the command can be shown with ``nodetool listsnapshots``. Any snapshot which refers to a dropped keyspace or dropped table **cannot** be listed, even if the snapshot still exists on disk (because the database information about these snapshots was deleted but snapshots remain on disk). You can locate these snapshots by looking for the ``snapshot`` directory using a `find <http://man7.org/linux/man-pages/man1/find.1.html>`_ command in Linux.
+
+Remove Snapshots
+----------------
+
+Snapshots are not removed automatically. On active database nodes, old snapshots take up disk space and need to be removed manually to free up the storage space. Snapshots are only taking additional space on disk once the original data files have been changed.
+
+.. caution:: Do not delete snapshots manually at the file system level, use the nodetool command.
+
+Use this procedure to remove snapshots or local backups.
+
+**Procedure**
+
+Use one of the following steps:
+
+To remove a specific snapshot from a specific keyspace:
+
+* Run ``nodetool clearsnapshot -t <snapshot_name> <keyspace_name>``. Note that the snapshot name in this command is a tag, a label, assigned to that snapshot.
+
+To remove the named snapshot from all keyspaces, that is, if any of the keyspaces happen to contain the named snapshot:
+
+* Run ``nodetool clearsnapshot -t <snapshot_name>`` command. Here the keyspace name was omitted.
+
+To remove all existing snapshots without any warning:
+
+* Run ``nodetool clearsnapshot``
+
+.. caution:: use caution when running ``nodetool clearsnapshot`` without specifying a keyspace or snapshot as this command will remove not only snapshots listed by “nodetool listsnapshots” command but all other snapshots on the node’s storage as well, including those for previously dropped tables or keyspaces.
+
+When all else fails, and you need to remove the snapshot manually:
+
+* If database can’t be brought up, it will be impossible for the nodetool command to list or delete snapshots. If, in this situation, the storage must be cleared of old snapshots, the only other remaining way would be removing snapshots manually, at the storage level, with the Linux `rm <http://man7.org/linux/man-pages/man1/rm.1.html>`_ command.
+
+.. note:: After you remove the snapshot with the ``rm`` command and the database which couldn't be brought up returns, ``nodetool listsnapshots`` may still list snapshots that were manually removed.
+
+
+
+Additional References
+---------------------
+
+* :doc:`Taking backups </operating-scylla/procedures/backup-restore/backup>` with snapshots.
+* :doc:`How snapshots are created on demand </operating-scylla/nodetool-commands/snapshot>` (rather than automatically when tables are dropped or truncated).
+* :doc:`Restoring from snapshots </operating-scylla/procedures/backup-restore/restore>`
+
diff --git a/docs/kb/static-columns.rst b/docs/kb/static-columns.rst
--- a/docs/kb/static-columns.rst
+++ b/docs/kb/static-columns.rst
@@ -0,0 +1,18 @@
+Scylla payload sent duplicated static columns
+=============================================
+Scylla payload, which refers to the actual network packets transferred from the Scylla server to the client as a result of a query, contains duplicate static columns.
+
+Issue description
+-----------------
+TCP trace analysis of the response for a query like the one listed below shows duplicate data (e.g., the current timestamp) was sent by the server.
+
+.. code-block:: none
+
+ select some_column, currentTimestamp() from some_table where pk = ?
+
+In another perspective, if you have 10 rows with a static column and a 10KB blob, the entire payload with all non-static columns included will exceed 100KB.
+
+
+Resolution
+----------
+A workaround for this issue would be to select the static column in a second request with LIMIT 1.
diff --git a/docs/kb/stop-local-repair.rst b/docs/kb/stop-local-repair.rst
--- a/docs/kb/stop-local-repair.rst
+++ b/docs/kb/stop-local-repair.rst
@@ -0,0 +1,43 @@
+Stopping a local repair
+=======================
+
+Issuing a stop to a running nodetool repair does not cause an immediate repair stop.
+
+
+Issue description
+-----------------
+
+I have started a local repair using ``nodetool repair``
+
+I have decided to stop the repair by issuing
+
+.. code-block:: sh
+
+ curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 'http://localhost:10000/storage_service/force_terminate_repair'
+
+
+Checking the repair status, I still see the repair running:
+
+.. code-block:: sh
+
+ curl -X GET --header 'Accept: application/json' 'http://localhost:10000/storage_service/active_repair/'
+ [1]
+
+
+Resolution
+----------
+
+**IMPORTANT:** Abort via the http rest api sets the abort flag and the abort does not happen immediately. The repair checks for the abort flag at the beginning of each step, e.g., negotiate_sync_boundary, get_missing_rows_from_follower_nodes, send_missing_rows_to_follower_nodes.
+
+Each step might take a while, so if you abort and check again immediately, the repair in question might still be in RUNNING state.
+
+Please check if the aborted repair stays in RUNNING forever before forcing a stop.
+
+*Force a repair stop:*
+
+.. code-block:: sh
+
+ curl -X POST "http://127.0.0.2:10000/storage_service/force_terminate_repair"
+
+
+**NOTE:** If you are using :doc:`Scylla Manager </operating-scylla/manager/index>` for repairs, a simple stop command via sctool already implements all the needed logic to gracefully stop a repair.
diff --git a/docs/kb/system-limits.rst b/docs/kb/system-limits.rst
--- a/docs/kb/system-limits.rst
+++ b/docs/kb/system-limits.rst
@@ -0,0 +1,20 @@
+System Limits
+-------------
+The following system limits should be set or removed.
+
+======= ============== ========================================
+Name Required value Description
+======= ============== ========================================
+core unlimited maximum core dump size
+------- -------------- ----------------------------------------
+memlock unlimited maximum locked-in-memory address space
+------- -------------- ----------------------------------------
+nofile 200000 maximum number of open file descriptors
+------- -------------- ----------------------------------------
+as unlimited address space limit
+------- -------------- ----------------------------------------
+nproc 8096 maximum number of processes
+======= ============== ========================================
+
+This configuration is provided in the file :code:`/etc/security/limits.d/scylla.conf`.
+
diff --git a/docs/kb/tombstones-flush.rst b/docs/kb/tombstones-flush.rst
--- a/docs/kb/tombstones-flush.rst
+++ b/docs/kb/tombstones-flush.rst
@@ -0,0 +1,51 @@
+=============================================
+How to flush old tombstones from a table
+=============================================
+
+**Audience: Devops professionals, architects**
+
+Description
+-----------
+If you have large partitions with lots of tombstones, you can use this workaround to flush the old tombstones.
+To avoid data resurrection, make sure that tables are repaired (either with nodetool repair or Scylla Manager) before the ``gc_grace_seconds`` threshold is reached.
+After the repair finishes, any tombstone older than the previous repair can be flushed.
+
+.. note:: Use :doc:`this article </troubleshooting/large-partition-table/>` to help you find large partitions.
+
+Steps:
+^^^^^^
+1. Run nodetool repair to synchronize the data between nodes. Alternatively, you can use Scylla Manager to run a repair.
+
+.. code-block:: sh
+
+ nodetool repair <options>;
+
+2. Set the ``gc_grace_seconds`` to the time since last repair was started - For instance, if the last repair was executed one day ago, then set ``gc_grace_seconds`` to one day (86400sec). For more information, please refer to :doc:`this KB article </kb/gc-grace-seconds/>`.
+
+.. note:: To prevent the compaction of unsynched tombstones, it is important to get the timing correctly. If you are not sure what time should set, please contact `Scylla support <https://www.scylladb.com/product/support/>`_.
+
+.. code-block:: sh
+
+ ALTER TABLE <keyspace>.<mytable> WITH gc_grace_seconds = <newTimeValue>;
+
+.. note:: Steps 3 & 4 should be repeated on ALL nodes affected with large tombstone partitions.
+
+3. Run nodetool flush
+
+.. code-block:: sh
+
+ nodetool flush <keyspace>.<mytable>;
+
+4. Run compaction (this will remove big partitions with tombstones from specified table)
+
+.. note:: By default, major compaction runs on all the keyspaces and tables, so if we want to specyfy e.g. only one table, we should point at it using arguments: ``<keyspace>.<mytable>``. For more information, please refer to `this article <https://docs.scylladb.com/operating-scylla/nodetool-commands/compact/>`_.
+
+.. code-block:: sh
+
+ nodetool compact <keyspace>.<mytable>;
+
+5. Alter the table and change the grace period back to the original ``gc_grace_seconds`` value.
+
+.. code-block:: sh
+
+ ALTER TABLE <keyspace>.<mytable> WITH gc_grace_seconds = <oldValue>;
diff --git a/docs/kb/ttl-facts.rst b/docs/kb/ttl-facts.rst
--- a/docs/kb/ttl-facts.rst
+++ b/docs/kb/ttl-facts.rst
@@ -0,0 +1,91 @@
+=================================
+Time to Live (TTL) and Compaction
+=================================
+
+**Topic: TTL, gc_grace_seconds, and Compaction**
+
+**Learn: How data is removed when using TTL**
+
+**Audience: All**
+
+
+Synopsis
+--------
+It is not always clear under which circumstances data is deleted when using Time to Live (TTL) and :ref:`gc_grace_seconds <gc_grace_seconds>` arguments in table definitions.
+This article clarifies what may not be apparent.
+It corrects some assumptions you may have that are not exactly true.
+
+
+Facts About Expiring Data
+-------------------------
+
+#. When compaction is running on an SSTable and it scans a piece of data that has expired the following happens:
+
+ * If the `data time stamp + gc_grace_seconds` is less than or equal to the current time (now), the data is thrown away and a tombstone is **not** created.
+ * If not, a tombstone is created and its timestamp is the same as its corresponding data. This means that the tombstone is going to be deleted after (at least) gc_grace_seconds from the time when the corresponding data element has been written.
+
+ For example:
+
+ In this example there is an expired cell that becomes a tombstone, note how the tombstone's local_deletion_time is the expired cell's timestamp.
+
+ .. code-block:: none
+
+ "rows" : [
+ {
+ "type" : "row",
+ "position" : 120,
+ "liveness_info" : { "tstamp" : "2017-04-09T17:07:12.702597Z",
+ "ttl" : 20, "expires_at" : "2017-04-09T17:07:32Z", "expired" : true },
+ "cells" : [
+ { "name" : "country", "value" : "1" },
+ ]
+
+ Is compacted into:
+
+ .. code-block:: none
+
+
+ "rows" : [
+ {
+ "type" : "row",
+ "position" : 79,
+ "cells" : [
+ { "name" : "country", "deletion_info" :
+ { "local_delete_time" : "2017-04-09T17:07:12Z" },
+ "tstamp" : "2017-04-09T17:07:12.702597Z"
+ },
+ ]
+
+#. If you set the TTL to be *greater* than the gc_grace_seconds, the expired data will **never** generate a tombstone.
+
+ Example: When Time Window Compaction Strategy (TWCS) estimates if a particular SSTable can be deleted it is going to treat expired data similarly as a tombstone:
+
+ .. code-block:: none
+
+ gc grace seconds: 0
+ sstable A: token range: [10, 10], timestamp range: [1, 1], ttl: 2, max deletion time: 3 (1+2)
+ sstable B: token range: [10, 10], timestamp range: [1, 5], ttl: 2, max deletion time: 7 (5+2)
+ now: 6
+
+ From this you can see that:
+
+ * SSTable A is fully expired because its max deletion time (3) is lower than now (6).
+ * SSTable B is NOT fully expired because its max deletion time (7) is greater than now (6).
+ * SSTable A will be added as a candidate for fully expired SSTable and will be purged.
+
+ During Compaction:
+
+ * Compaction sees that SSTable B overlaps with SSTable A in token range.
+ * Compaction also sees that SSTable A overlaps with B in timestamp range, and it thinks that SSTable A could have a tombstone that shadows data in SSTable B.
+ * Compaction decides not to purge SSTable A even though it's fully expired.
+
+#. If you use updates in conjunction with TWCS, it may prevent the "window compacted" SSTables from being deleted when they should have been.
+ However, when the corresponding data expires (in all SSTables), all relevant SSTables are will be deleted during the next compaction.
+
+
+Additional Information
+----------------------
+
+* :doc:`How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds/>`
+* :doc:`Expiring Data with Time to Live (TTL) </getting-started/time-to-live/>`
+* :ref:`CQL Reference: Table Options <create-table-general-options>`
diff --git a/docs/kb/unresponsive-nodes.rst b/docs/kb/unresponsive-nodes.rst
--- a/docs/kb/unresponsive-nodes.rst
+++ b/docs/kb/unresponsive-nodes.rst
@@ -0,0 +1,51 @@
+==============================
+Scylla Nodes are Unresponsive
+==============================
+
+**Topic: Performance Analysis**
+
+**Issue:**
+
+Scylla nodes are unresponsive. They are shown as down, and I can't even establish new SSH connections to the cluster. The existing connections are slow.
+
+**Environment: All**
+
+
+
+Root Cause
+----------
+
+When Scylla is reporting itself as down, this may mean a Scylla-specific issue. But when the node as a whole starts reporting slowness and even establishing SSH connections is hard, that usually indicates a node level issue.
+
+The most common cause is due to swap. There are two main situations we need to consider:
+
+* The system has swap configured. If the system needs to swap pages, it may swap the Scylla memory, and future access to that memory will be slow.
+
+* The system does not have swap configured. In that case the kernel may go on a loop trying to free pages without being able to so, becoming a CPU-hog which eventually stalls the Scylla and other processes from executing.
+
+
+
+Resolution
+----------
+
+1. Ideally, a healthy system should not swap. Scylla pre-allocates 93% of the memory by default, and never uses more than that. It leaves the remaining 7% of the memory for other tasks including the Operating System. Check with the ``top`` utility if there are other processes running which are consuming a lot of memory.
+
+ * If there are other processes running but they are not essential, we recommend moving them to other machines.
+ * If there are other processes running and they are essential, the default reservation may not be enough. Change the reservation following the steps below.
+
+
+ Swap can be set up in several ways. One way to set up swap is detailed in the KB Article :doc:`How to Setup a Swap Space </kb/set-up-swap>`.
+
+
+2. Having swap enabled and not using it is better than needing swap and not having it. Configure a file or partition to be used as swap for production deployments.
+
+Change memory reservation
+-------------------------
+
+Add ``--reserve-memory [memory]`` to the scylla command line at:
+
+* ``/etc/sysconfig/scylla-server`` (RHEL variants) or
+* ``/etc/defaults/scylla-server`` (Debian variants)
+
+For example ``--reserve-memory 10G`` (will reserve 10G)
+
diff --git a/docs/kb/update-pk.rst b/docs/kb/update-pk.rst
--- a/docs/kb/update-pk.rst
+++ b/docs/kb/update-pk.rst
@@ -0,0 +1,17 @@
+==============================
+Update a Primary Key
+==============================
+
+**Topic: Can you Update a Primary Key in Scylla?**
+
+**Audience: Scylla administrators**
+
+In Scylla, you cannot update a primary key. It is impossible to do so.
+
+However, you can migrate the data from the old table with the old primary key to a new table with a new primary key.
+There are two ways to handle the migration:
+
+* Fork-lifting the historical data with the :doc:`Spark Migrator </using-scylla/mig-tool-review/>` tool.
+* Double writing the new data.
+
+If you are running Scylla Enterprise it is advantageous to control the migration resources using :doc:`Workload Prioritization </using-scylla/workload-prioritization/>`.
diff --git a/docs/kb/use-perf.rst b/docs/kb/use-perf.rst
--- a/docs/kb/use-perf.rst
+++ b/docs/kb/use-perf.rst
@@ -0,0 +1,60 @@
+==================================
+Using the perf utility with Scylla
+==================================
+
+.. meta::
+ :title:
+ :description: Debugging or Diving into a Pegged Shard
+ :keywords: perf, pegged shard, list processes, analyze perf issue
+
+This article contains useful tips & tricks for using the `perf` utility with Scylla.
+The `perf` utility is particularly useful when debugging a pegged shard.
+
+
+Due to its thread-per-core nature, looking at aggregates is rarely useful as it tends to hide bad behavior that is localized to specific CPUs. Looking at an individual CPU will make those anomalies easier to see. Once you notice that a Scylla shard requires investigation (for example, when the Scylla Monitor shard view shows that a particular shard is more loaded than others), you can use the ``seastar-cpu-map.sh`` script described :doc:`here </kb/map-cpu/>` to determine which Linux CPU hosts that Scylla shard. For example:
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla -s 0
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+
+In the above example, shard 0 is investigated using the ``-s`` argument and providing the shard number. The results show that shard 0 runs on Linux CPU 1. In all ``perf`` commands that follow, you can add the ``-C 1`` argument to restrict ``perf`` to look only at CPU 1.
+
+When is perf useful?
+--------------------
+
+`Perf`` is most useful when the CPU being probed runs at 100% utilization so that you can identify large chunks of execution time used by particular functions.
+
+Note that due to polling, Scylla will easily drive CPUs to 100% even when it is not bottlenecked. It will spin (poll) for some time, waiting for new requests. It tends to show in the perf reports as functions related to polling having high CPU time.
+
+Perf can also be a useful tool when you suspect that something that shouldn’t be running is running. One example is systems with very high ``reactor_utilization`` (indicating non-polling work), where the Linux view of ``system`` CPU utilization is also high. It indicates that the Linux Kernel, not Scylla, is the main user of the CPU, so additional investigation is needed.
+
+perf top
+--------
+
+Perf top shows a point-in-time view of the system. The figure below shows the result of running ``perf top -C 1``.
+
+.. image:: perf-top.png
+
+Callgraphs
+----------
+
+``Perf`` can generate callgraphs. They are useful when you want to understand the complete call chain that results in a function being called. You can add ``--call-graph=dwarf -F 99`` to any recording command, such as ``perf top`` or ``perf record``, to generate a callgraph.
+
+For example, to record the callgraphs in CPU2:
+
+.. code-block:: bash
+
+ sudo perf record -C 2 --call-graph=dwarf -F 99
+
+You can dump the results to the ``trace.txt`` file by running:
+
+.. code-block:: bash
+
+ sudo perf report --no-children --stdio > /tmp/trace.txt
+
diff --git a/docs/kb/write-path-image-memtable-sstable.png b/docs/kb/write-path-image-memtable-sstable.png
--- a/docs/kb/write-path-image-memtable-sstable.png
+++ b/docs/kb/write-path-image-memtable-sstable.png
null
diff --git a/docs/kb/yaml-address.rst b/docs/kb/yaml-address.rst
--- a/docs/kb/yaml-address.rst
+++ b/docs/kb/yaml-address.rst
@@ -0,0 +1,71 @@
+
+Configure Scylla Networking with Multiple NIC/IP Combinations
+=============================================================
+
+There are many ways to configure IP addresses in scylla.yaml. Setting the IP addresses incorrectly, can yield less than optimal results. This article focuses on configuring the addresses which are vital to network communication.
+
+This article contains examples of the different ways to configure networking in scylla.yaml. The entire scope for address configuration is in the :ref:`Admin guide <admin-address-configuration-in-scylla>`.
+
+As these values depend on a particular network configuration in your setup there are a few ways to configure the address parameters. In the examples below, we will provide instructions for the most common use cases (all in the resolution of a single Scylla node).
+
+1 NIC, 1 IP
+-----------
+
+This is the case where a Scylla cluster is meant to operate in a single subnet with a single address space (no "public/internal IP"s).
+
+In this case:
+
+* IP = node's IP address
+
+.. code-block:: none
+
+ listen_address: IP
+ rpc_address: IP
+ broadcast_address: not set
+ broadcast_rpc_address: not set
+ endpoint_snitch: no restrictions
+
+1 NIC, 2 IPs
+------------
+
+This is the case where you are using Public and Internal IP addresses. AWS instances with public IP addresses is a classic example of this configuration.
+
+In this case:
+
+* IPp = the node's public IP address
+* IPi = the node's internal IP address
+
+IPi is the IP configured to the same IP as the NIC (from the OS perspective) and when running the ip command, the output displays this IP address. For ip command parameters, refer to your Linux distro documentation.
+
+.. code-block:: none
+
+ listen_address: IPi
+ rpc_address: IPi
+ broadcast_address: IPp
+ broadcast_rpc_address: IPp
+ endpoint_snitch: GossipintPropertyFileSnitch with prefer_local=true | any of Ec2xxxSnitch snitches.
+
+2 NICs, 2 IPs
+-------------
+
+This is the case where a user wants CQL requests or responses to be sent via one subnet (net1) and inter-node communication to go over another subnet (net2).
+
+In this case:
+
+* IP1 = node's IP in net1 subnet
+* IP2 = node's IP in net2 subnet
+
+.. code-block:: none
+
+ listen_address: IP2
+ rpc_address: IP1
+ broadcast_address: not set
+ broadcast_rpc_address: not set
+ endpoint_snitch: no restrictions
+
+
+Additional References
+---------------------
+
+:doc:`Administration Guide </operating-scylla/admin>` - User guide for Scylla Administration
+
diff --git a/docs/operating-scylla/_common/decommission_warning.rst b/docs/operating-scylla/_common/decommission_warning.rst
--- a/docs/operating-scylla/_common/decommission_warning.rst
+++ b/docs/operating-scylla/_common/decommission_warning.rst
@@ -0,0 +1,4 @@
+.. warning::
+
+ Review current disk space utilization on existing nodes and make sure the amount of data streamed from the node being removed can fit into the disk space available on the remaining nodes. If there is not enough disk space on the remaining nodes, the removal of a node will fail. Add more storage to remaining nodes **before** starting the removal procedure.
+
diff --git a/docs/operating-scylla/_common/networking-ports.rst b/docs/operating-scylla/_common/networking-ports.rst
--- a/docs/operating-scylla/_common/networking-ports.rst
+++ b/docs/operating-scylla/_common/networking-ports.rst
@@ -0,0 +1,30 @@
+
+Scylla uses the following ports:
+
+====== ============================================ ========
+Port Description Protocol
+====== ============================================ ========
+9042 CQL (native_transport_port) TCP
+------ -------------------------------------------- --------
+9142 SSL CQL (secure client to node) TCP
+------ -------------------------------------------- --------
+7000 Inter-node communication (RPC) TCP
+------ -------------------------------------------- --------
+7001 SSL inter-node communication (RPC) TCP
+------ -------------------------------------------- --------
+7199 JMX management TCP
+------ -------------------------------------------- --------
+10000 Scylla REST API TCP
+------ -------------------------------------------- --------
+9180 Prometheus API TCP
+------ -------------------------------------------- --------
+9100 node_exporter (Optionally) TCP
+------ -------------------------------------------- --------
+9160 Scylla client port (Thrift) TCP
+------ -------------------------------------------- --------
+19042 Native shard-aware transport port TCP
+------ -------------------------------------------- --------
+19142 Native shard-aware transport port (ssl) TCP
+====== ============================================ ========
+
+.. note:: For Scylla Manager ports, see `Scylla Manager <https://scylladb.github.io/scylla-manager/>`_.
diff --git a/docs/operating-scylla/_common/tools_index.rst b/docs/operating-scylla/_common/tools_index.rst
--- a/docs/operating-scylla/_common/tools_index.rst
+++ b/docs/operating-scylla/_common/tools_index.rst
@@ -0,0 +1,21 @@
+* :doc:`Nodetool Reference</operating-scylla/nodetool>` - Scylla commands for managing Scylla node or cluster using the command-line nodetool utility.
+* :doc:`CQLSh - the CQL shell</getting-started/cqlsh>`.
+* :doc:`REST - Scylla REST/HTTP Admin API</operating-scylla/rest>`.
+* :doc:`Tracing </using-scylla/tracing>` - a ScyllaDB tool for debugging and analyzing internal flows in the server.
+* :doc:`SSTableloader </operating-scylla/admin-tools/sstableloader>` - Bulk load the sstables found in the directory to a Scylla cluster
+* :doc:`scylla-sstable </operating-scylla/admin-tools/scylla-sstable>` - Validates and dumps the content of SStables, generates a histogram, dumps the content of the SStable index.
+* :doc:`scylla-types </operating-scylla/admin-tools/scylla-types/>` - Examines raw values obtained from SStables, logs, coredumps, etc.
+* :doc:`cassandra-stress </operating-scylla/admin-tools/cassandra-stress/>` A tool for benchmarking and load testing a Scylla and Cassandra clusters.
+* :doc:`SSTabledump - Scylla 3.0, Scylla Enterprise 2019.1 and newer versions </operating-scylla/admin-tools/sstabledump>`
+* :doc:`SSTable2JSON - Scylla 2.3 and older </operating-scylla/admin-tools/sstable2json>`
+* sstablelevelreset - Reset level to 0 on a selected set of SSTables that use LeveledCompactionStrategy (LCS).
+* :doc:`SSTable-Index </operating-scylla/admin-tools/sstable-index>` - A tool which lists all partitions contained in an SSTable index.
+* sstablemetadata - Prints metadata about a specified SSTable.
+* sstablerepairedset - Mark specific SSTables as repaired or unrepaired.
+* configuration_encryptor - :doc:`encrypt at rest </operating-scylla/security/encryption-at-rest>` sensitive scylla configuration entries using system key.
+* local_file_key_generator - Generate a local file (system) key for :doc:`encryption at rest </operating-scylla/security/encryption-at-rest>`, with the provided length, Key algorithm, Algorithm block mode and Algorithm padding method.
+* `scyllatop <https://www.scylladb.com/2016/03/22/scyllatop/>`_ - A terminal base top-like tool for scylladb collectd/prometheus metrics.
+* :doc:`scylla_dev_mode_setup</getting-started/install-scylla/dev-mod>` - run Scylla in Developer Mode.
+* :doc:`perftune</operating-scylla/admin-tools/perftune>` - performance configuration.
+
+Run each tool with ``-h``, ``--help`` for full options description.
diff --git a/docs/operating-scylla/admin-tools/cassandra-stress.rst b/docs/operating-scylla/admin-tools/cassandra-stress.rst
--- a/docs/operating-scylla/admin-tools/cassandra-stress.rst
+++ b/docs/operating-scylla/admin-tools/cassandra-stress.rst
@@ -0,0 +1,277 @@
+Cassandra Stress
+================
+
+The cassandra-stress tool is used for benchmarking and load testing both Scylla and Cassandra clusters. The cassandra-stress tool also supports testing arbitrary CQL tables and queries to allow users to benchmark their data model.
+
+This documentation focuses on user mode as this allows the testing of your actual schema.
+
+Usage
+-----
+
+There are several operation types:
+
+* write-only, read-only, and mixed workloads of standard data
+* write-only and read-only workloads for counter columns
+* user configured workloads, running custom queries on custom schemas
+* The syntax is cassandra-stress <command> [options]. If you want more information on a given command or options, just run cassandra-stress help
+
+Commands:
+
+read: Multiple concurrent reads - the cluster must first be populated by a write test.
+
+write: Multiple concurrent writes against the cluster.
+
+mixed: Interleaving of any basic commands, with configurable ratio and distribution - the cluster must first be populated by a write test.
+
+counter_write: Multiple concurrent updates of counters.
+
+counter_read: Multiple concurrent reads of counters. The cluster must first be populated by a counterwrite test.
+
+user: Interleaving of user provided queries, with configurable ratio and distribution.
+
+help: Print help for a command or option.
+
+print: Inspect the output of a distribution definition.
+
+legacy: Legacy support mode.
+
+Primary Options:
+
+-pop: Population distribution and intra-partition visit order.
+
+-insert: Insert specific options relating to various methods for batching and splitting partition updates.
+
+-col: Column details such as size and count distribution, data generator, names, comparator and if super columns should be used.
+
+-rate: Thread count, rate limit or automatic mode (default is auto).
+
+-mode: Thrift or CQL with options.
+
+-errors: How to handle errors when encountered during stress.
+
+-sample: Specify the number of samples to collect for measuring latency.
+
+-schema: Replication settings, compression, compaction, etc.
+
+-node: Nodes to connect to.
+
+-log: Where to log progress to, and the interval at which to do it.
+
+-transport: Custom transport factories.
+
+-port: The port to connect to cassandra nodes on.
+
+-sendto: Specify a stress server to send this command to.
+
+-graph: Graph recorded metrics.
+
+-tokenrange: Token range settings.
+
+User mode
+---------
+
+User mode allows you to use your stress your own schemas. This can save time in the long run rather than building an application and then realising your schema doesn’t scale.
+
+Profile
+.......
+
+User mode requires a profile defined in YAML. Multiple YAML files may be specified in which case operations in the ops argument are referenced as specname.opname.
+
+An identifier for the profile:
+
+.. code-block:: cql
+
+ specname: staff_activities
+
+The keyspace for the test:
+
+.. code-block:: cql
+
+ keyspace: staff
+
+CQL for the keyspace. Optional if the keyspace already exists:
+
+.. code-block:: cql
+
+ keyspace_definition: |
+ CREATE KEYSPACE stresscql WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};
+
+The table to be stressed:
+
+.. code-block:: cql
+
+ table: staff_activities
+
+CQL for the table. Optional if the table already exists:
+
+.. code-block:: cql
+
+ table_definition: |
+ CREATE TABLE staff_activities (
+ name text,
+ when timeuuid,
+ what text,
+ PRIMARY KEY(name, when, what)
+ )
+
+Optional meta information on the generated columns in the above table. The min and max only apply to text and blob types. The distribution field represents the total unique population distribution of that column across rows:
+
+.. code-block:: cql
+
+ columnspec:
+ - name: name
+ size: uniform(5..10) # The names of the staff members are between 5-10 characters
+ population: uniform(1..10) # 10 possible staff members to pick from
+ - name: when
+ cluster: uniform(20..500) # Staff members do between 20 and 500 events
+ - name: what
+ size: normal(10..100,50)
+
+Supported types are:
+
+An exponential distribution over the range [min..max]:
+
+.. code-block:: cql
+
+ EXP(min..max)
+
+An extreme value (Weibull) distribution over the range [min..max]:
+
+.. code-block:: cql
+
+ EXTREME(min..max,shape)
+
+A gaussian/normal distribution, where mean=(min+max)/2, and stdev is (mean-min)/stdvrng:
+
+.. code-block:: cql
+
+ GAUSSIAN(min..max,stdvrng)
+
+A gaussian/normal distribution, with explicitly defined mean and stdev:
+
+.. code-block:: cql
+
+ GAUSSIAN(min..max,mean,stdev)
+
+A uniform distribution over the range [min, max]:
+
+.. code-block:: cql
+
+ UNIFORM(min..max)
+
+A fixed distribution, always returning the same value:
+
+.. code-block:: cql
+
+ FIXED(val)
+
+If preceded by ~, the distribution is inverted
+
+Defaults for all columns are size: uniform(4..8), population: uniform(1..100B), cluster: fixed(1)
+
+Insert distributions:
+
+.. code-block:: cql
+
+ insert:
+ # How many partition to insert per batch
+ partitions: fixed(1)
+ # How many rows to update per partition
+ select: fixed(1)/500
+ # UNLOGGED or LOGGED batch for insert
+ batchtype: UNLOGGED
+
+Currently all inserts are done inside batches.
+
+Read statements to use during the test:
+
+.. code-block:: cql
+
+ queries:
+ events:
+ cql: select * from staff_activities where name = ?
+ fields: samerow
+ latest_event:
+ cql: select * from staff_activities where name = ? LIMIT 1
+ fields: samerow
+
+Running a user mode test:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./example.yaml duration=1m "ops(insert=1,latest_event=1,events=1)" truncate=once
+
+This will create the schema then run tests for 1 minute with an equal number of inserts, latest_event queries and events queries. Additionally the table will be truncated once before the test.
+
+The full example can be found here yaml
+
+Running a user mode test with multiple yaml files:
+
+.. code-block::
+
+ cassandra-stress user profile=./example.yaml,./example2.yaml duration=1m “ops(ex1.insert=1,ex1.latest_event=1,ex2.insert=2)” truncate=once
+
+This will run operations as specified in both the example.yaml and example2.yaml files. example.yaml and example2.yaml can reference the same table
+although care must be taken that the table definition is identical (data generation specs can be different).
+
+.. Lightweight transaction support
+.. ...............................
+
+.. cassandra-stress supports lightweight transactions. In this it will first read current data from Cassandra and then uses read value(s) to fulfill lightweight transaction condition(s).
+
+.. Lightweight transaction update query:
+
+.. .. code-block:: cql
+
+.. queries:
+.. regularupdate:
+.. cql: update blogposts set author = ? where domain = ? and published_date = ?
+.. fields: samerow
+.. updatewithlwt:
+.. cql: update blogposts set author = ? where domain = ? and published_date = ? IF body = ? AND url = ?
+.. fields: samerow
+
+Graphing
+........
+
+Graphs can be generated for each run of stress.
+
+.. image:: example-stress-graph.png
+
+To create a new graph:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./stress-example.yaml "ops(insert=1,latest_event=1,events=1)" -graph file=graph.html title="Awesome graph"
+
+To add a new run to an existing graph point to an existing file and add a revision name:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./stress-example.yaml duration=1m "ops(insert=1,latest_event=1,events=1)" -graph file=graph.html title="Awesome graph" revision="Second run"
+
+FAQ
+...
+
+How do you use NetworkTopologyStrategy for the keyspace?
+
+Use the schema option making sure to either escape the parenthesis or enclose in quotes:
+
+.. code-block:: cql
+
+ cassandra-stress write -schema "replication(strategy=NetworkTopologyStrategy,datacenter1=3)"
+
+How do you use SSL?
+
+Use the transport option:
+
+.. code-block:: cql
+
+ cassandra-stress "write n=100k cl=ONE no-warmup" -transport "truststore=$HOME/jks/truststore.jks truststore-password=cassandra"
+
+
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+
diff --git a/docs/operating-scylla/admin-tools/example-stress-graph.png b/docs/operating-scylla/admin-tools/example-stress-graph.png
--- a/docs/operating-scylla/admin-tools/example-stress-graph.png
+++ b/docs/operating-scylla/admin-tools/example-stress-graph.png
null
diff --git a/docs/operating-scylla/admin-tools/index.rst b/docs/operating-scylla/admin-tools/index.rst
--- a/docs/operating-scylla/admin-tools/index.rst
+++ b/docs/operating-scylla/admin-tools/index.rst
@@ -0,0 +1,31 @@
+Admin Tools
+============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ Nodetool Reference </operating-scylla/nodetool>
+ CQLSh </getting-started/cqlsh>
+ REST </operating-scylla/rest>
+ Tracing </using-scylla/tracing>
+ scylla-sstable
+ scylla-types </operating-scylla/admin-tools/scylla-types/>
+ sstableloader
+ cassandra-stress </operating-scylla/admin-tools/cassandra-stress/>
+ sstabledump
+ sstable2json
+ sstable-index
+ Scylla Logs </getting-started/logging/>
+ perftune
+ Virtual Tables </operating-scylla/admin-tools/virtual-tables/>
+
+
+.. panel-box::
+ :title: Admin Tools
+ :id: "getting-started"
+ :class: my-panel
+
+ .. include:: /operating-scylla/_common/tools_index.rst
+
+The `Admin Procedures and Monitoring lesson <https://university.scylladb.com/courses/scylla-operations/lessons/admin-procedures-and-basic-monitoring/topic/admin-procedures-and-monitoring/>`_ on Scylla University provides more training and examples material on this subject.
diff --git a/docs/operating-scylla/admin-tools/perftune.rst b/docs/operating-scylla/admin-tools/perftune.rst
--- a/docs/operating-scylla/admin-tools/perftune.rst
+++ b/docs/operating-scylla/admin-tools/perftune.rst
@@ -0,0 +1,51 @@
+Seastar Perftune
+================
+
+Configure various system parameters to improve the seastar application performance, called from of scylla_setup script.
+
+This script will:
+
+* Ban relevant IRQs from being moved by irqbalance.
+* Configure various system parameters in /proc/sys.
+* Distribute the IRQs (using SMP affinity configuration) among CPUs according to the configuration mode (see below).
+
+As a result, some of the CPUs may be destined only to handle the IRQs and taken out of the CPU set to be used to run the seastar application ("compute CPU set").
+
+
+perftune.py [options]
+
+Options:
+
+* ``--mode`` - configuration mode (see below)
+* ``--nic`` - network interface name(s), by default uses *eth0* (may appear more than once)
+* ``--tune-clock`` - Force tuning of the system clocksource
+* ``--get-cpu-mask`` - print the CPU mask to be used for compute
+* ``--get-cpu-mask-quiet`` - print the CPU mask to be used for compute, print the zero CPU set if that's what it turns out to be
+* ``--verbose`` - be more verbose about operations and their result
+* ``--tune`` - components to configure (may be given more than once)
+* ``--cpu-mask`` - mask of cores to use, by default use all available cores
+* ``--irq-cpu-mask``- mask of cores to use for IRQs binding
+* ``--dir`` - directory to optimize (may appear more than once)
+* ``--dev`` device to optimize (may appear more than once), e.g. sda1
+* ``--options-file`` - configuration YAML file
+* ``--dump-options-file`` - Print the configuration YAML file containing the current configuration
+* ``--dry-run`` - Don't take any action, just recommend what to do
+* ``--write-back-cache`` Enable/Disable *write back* write cache mode
+
+Modes description:
+
+* *sq* - set all IRQs of a given NIC to CPU0 and configure RPS to spreads NAPIs' handling between other CPUs.
+* *sq_split* - divide all IRQs of a given NIC between CPU0 and its HT siblings and configure RPS to spreads NAPIs' handling between other CPUs.
+* *mq* - distribute NIC's IRQs among all CPUs instead of binding them all to CPU0. In this mode RPS is always enabled to spreads NAPIs' handling between all CPUs.
+
+If there isn't any mode given script will use a default mode:
+
+- If number of physical CPU cores per Rx HW queue is greater than 4 - use the 'sq-split' mode.
+- Otherwise, if number of hyperthreads per Rx HW queue is greater than 4 - use the 'sq' mode.
+- Otherwise use the 'mq' mode.
+
+Default values:
+
+* --nic NIC: eth0
+* --cpu-mask MASK: all available cores mask
+* --tune-clock: false
diff --git a/docs/operating-scylla/admin-tools/scylla-sstable.rst b/docs/operating-scylla/admin-tools/scylla-sstable.rst
--- a/docs/operating-scylla/admin-tools/scylla-sstable.rst
+++ b/docs/operating-scylla/admin-tools/scylla-sstable.rst
@@ -0,0 +1,72 @@
+scylla-sstable
+==============
+
+.. versionadded:: 5.0
+
+Introduction
+-------------
+
+This tool allows you to examine the content of SStables by performing operations such as dumping the content of SStables,
+generating a histogram, validating the content of SStables, and more. See `Supported Operations`_ for the list of available operations.
+
+Run ``scylla-sstable --help`` for additional information about the tool and the operations.
+
+Usage
+------
+
+Syntax
+^^^^^^
+
+The command syntax is as follows:
+
+.. code-block:: console
+
+ scylla-sstable <operation> <path to SStable>
+
+
+You can specify more than one SStable.
+
+Supported Operations
+^^^^^^^^^^^^^^^^^^^^^^^
+The ``dump-*`` operations output JSON. For ``dump-data``, you can specify another output format.
+
+* ``dump-data`` - Dumps the content of the SStable. You can use it with additional parameters:
+
+ * ``--merge`` - Allows you to process multiple SStables as a unified stream (if not specified, multiple SStables are processed one by one).
+ * ``--partition={{<partition key>}}`` or ``partitions-file={{<partition key>}}`` - Allows you to narrow down the scope of the operation to specified partitions. To specify the partition(s) you want to be processed, provide partition keys in the hexdump format used by ScyllaDB (the hex representation of the raw buffer).
+ * ``--output-format=<format>`` - Allows you to specify the output format: ``json`` or ``text``.
+
+* ``dump-index`` - Dumps the content of the SStable index.
+* ``dump-compression-info`` - Dumps the SStable compression information, including compression parameters and mappings between
+ compressed and uncompressed data.
+* ``dump-summary`` - Dumps the summary of the SStable index.
+* ``dump-statistics`` - Dumps the statistics of the SStable, including metadata about the data component.
+* ``dump-scylla-metadata`` - Dumps the SStable's scylla-specific metadata.
+* ``writetime-histogram`` - Generates a histogram of all the timestamps in the SStable. You can use it with a parameter:
+
+ * ``--bucket=<unit>`` - Allows you to specify the unit of time to be used as bucket (years, months, weeks, days, or hours).
+
+* ``validate`` - Validates the content of the SStable with the mutation fragment stream validator.
+* ``validate-checksums`` - Validates SStable checksums (full checksum and per-chunk checksum) against the SStable data.
+* ``decompress`` - Decompresses the data component of the SStable (the ``*-Data.db`` file) if compressed. The decompressed data is written to a ``*-Data.decompressed`` file.
+
+Examples
+^^^^^^^^
+Dumping the content of the SStable:
+
+.. code-block:: console
+
+ scylla-sstable dump-data /path/to/md-123456-big-Data.db
+
+Dumping the content of two SStables as a unified stream:
+
+.. code-block:: console
+
+ scylla-sstable dump-data --merge /path/to/md-123456-big-Data.db /path/to/md-123457-big-Data.db
+
+
+Validating the specified SStables:
+
+.. code-block:: console
+
+ scylla-sstable validate /path/to/md-123456-big-Data.db /path/to/md-123457-big-Data.db
diff --git a/docs/operating-scylla/admin-tools/scylla-types.rst b/docs/operating-scylla/admin-tools/scylla-types.rst
--- a/docs/operating-scylla/admin-tools/scylla-types.rst
+++ b/docs/operating-scylla/admin-tools/scylla-types.rst
@@ -0,0 +1,140 @@
+scylla-types
+==============
+
+.. versionadded:: 5.0
+
+Introduction
+-------------
+This tool allows you to examine raw values obtained from SStables, logs, coredumps, etc., by performing operations on them,
+such as ``print``, ``compare``, or ``validate``. See :ref:`Supported Operations <scylla-types-operations>` for details.
+
+Run ``scylla types --help`` for additional information about the tool and the operations.
+
+Usage
+------
+
+Syntax
+^^^^^^
+
+The command syntax is as follows:
+
+.. code-block:: console
+
+ scylla types <operation> [options] <hex_value1> [hex_value2]
+
+
+* Provide the values in the hex form without a leading 0x prefix.
+* You must specify the type of the provided values. See :ref:`Specifying the Value Type <scylla-types-type>`.
+* The number of provided values depends on the operation. See :ref:`Supported Operations <scylla-types-operations>` for details.
+* The scylla-types operations come with additional options. See :ref:`Additional Options <scylla-types-options>` for the list of options.
+
+.. _scylla-types-type:
+
+Specifying the Value Type
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You must specify the type of the value(s) you want to examine by adding the ``-t [type name]`` option to the operation.
+Specify the type by providing its Cassandra class name (the prefix can be omitted, for example, you can provide ``Int32Type``
+instead of ``org.apache.cassandra.db.marshal.Int32Type``). See https://github.com/scylladb/scylla/blob/master/docs/design-notes/cql3-type-mapping.md for a mapping of cql3 types to Cassandra type class names.
+
+If you provide more than one value, all of the values must share the same type. For example:
+
+.. code-block:: console
+
+ scylla types print -t Int32Type b34b62d4 00783562
+
+.. _scylla-types-compound:
+
+**Compounds**
+
+A compound is a single value that is composed of multiple values of possibly different types. An example of a compound value is a clustering key or a partition key.
+
+You can use the ``--prefix-compound`` or ``--full-compound`` options to indicate that the provided value is a compound
+(see :ref:`Additional Options <scylla-types-options>`) for details.
+
+When a value is a compound, you can specify a different type for each value making up the compound, **respectively** (i.e., the order
+of the types on the command line must be the same as the order in the compound). For example:
+
+.. code-block:: console
+
+ scylla types print --prefix-compound -t TimeUUIDType -t Int32Type 0010d00819896f6b11ea00000000001c571b000400000010
+
+
+.. _scylla-types-operations:
+
+Supported Operations
+^^^^^^^^^^^^^^^^^^^^^^^
+* ``print`` - Deserializes and prints the provided value in a human-readable form. Required arguments: 1 or more serialized values.
+* ``compare`` - Compares two values and print the result. Required arguments: 2 serialized values.
+* ``validate`` - Verifies if the value is valid for the type, according to the requirements of the type. Required arguments: 1 or more serialized values.
+
+
+.. _scylla-types-options:
+
+Additional Options
+^^^^^^^^^^^^^^^^^^^
+
+You can run ``scylla types [operation] --help`` for additional information on a given operation.
+
+* ``-h`` ( or ``--help``) - Prints the help message.
+* ``--help-seastar`` - Prints the help message about the Seastar options.
+* ``--help-loggers`` - Prints a list of logger names.
+* ``-t`` ( or ``--type``) - Specifies the type of the provided value. See :ref:`Specifying the Value Type <scylla-types-type>`.
+* ``--prefix-compound`` - Indicates that the value is a prefixable compound (e.g., clustering key) composed of multiple values of possibly different types.
+* ``--full-compound`` - Indicates that the value is a full compound (e.g., partition key) composed of multiple values of possibly different types.
+* ``--value arg`` - Specifies the value to process (if not provided as a positional argument).
+
+Examples
+^^^^^^^^
+* Deserializing and printing a value of type Int32Type:
+
+ .. code-block:: console
+
+ scylla types print -t Int32Type b34b62d4
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ -1286905132
+
+* Validating a value of type Int32Type:
+
+ .. code-block:: console
+
+ scylla types validate -t Int32Type b34b62d4
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ b34b62d4: VALID - -1286905132
+
+* Comparing two values of ReversedType(TimeUUIDType):
+
+ .. code-block:: console
+
+ scylla types compare -t 'ReversedType(TimeUUIDType)' b34b62d46a8d11ea0000005000237906 d00819896f6b11ea00000000001c571b
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ b34b62d4-6a8d-11ea-0000-005000237906 > d0081989-6f6b-11ea-0000-0000001c571b
+
+* Deserializing and printing a compound value:
+
+ .. code-block:: console
+
+ scylla types print --prefix-compound -t TimeUUIDType -t Int32Type 0010d00819896f6b11ea00000000001c571b000400000010
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ (d0081989-6f6b-11ea-0000-0000001c571b, 16)
+
diff --git a/docs/operating-scylla/admin-tools/sstable-index.rst b/docs/operating-scylla/admin-tools/sstable-index.rst
--- a/docs/operating-scylla/admin-tools/sstable-index.rst
+++ b/docs/operating-scylla/admin-tools/sstable-index.rst
@@ -0,0 +1,64 @@
+SSTable Index
+=============
+
+.. versionadded:: 4.4 Scylla Open Source
+
+*scylla-sstable-index* is a tool which lists all partitions contained in an SSTable index.
+As all partitions in an SSTable are indexed, this tool can be used to find out
+what partitions are contained in a given SSTable.
+
+The command syntax is as follows:
+
+.. code-block:: none
+
+ ./scylla-sstable-index [--type=<CassandraType>] <--sstable> [path/to/scylla/datadir]
+
+Where:
+
+* The ``--type`` or ``-t`` flag is used to specify the types making up the partition key of the table to which the index file belongs.
+ This is needed so the tool can parse the SSTable keys found in the index. You will need to pass ``--type|-t`` for each type in the partition key.
+ For the type names, the Cassandra type class notation has to be used. You can use the short form, i.e. without the org.apache.cassandra.db.marshal. prefix.
+ For a complete mapping of CQL types to their respective Cassandra type class notation, see `CQL3 Type Mapping <https://scylla.docs.scylladb.com/master/design-notes/cql3-type-mapping.html#cql3-type-mapping>`_.
+
+* The SSTable index file path can be passed both as a positional argument ``[path/to/scylla/datadir]`` or with the ``--sstable`` flag.
+
+The output has the following format:
+
+``$pos: $human_readable_value (pk{$raw_hex_value})``
+
+Where:
+
+* ``$pos:`` the position of the partition in the (decompressed) data file
+* ``$human_readable_value:`` the human readable partition key
+* ``$raw_hex_value:`` the raw hexadecimal value of the binary representation of the partition key
+
+
+Example
+-------
+
+If you have the following schema:
+
+.. code-block:: none
+
+ CREATE TABLE my_keyspace.my_table (
+ id1 int,
+ id2 text,
+ value text,
+ PRIMARY KEY ((id1, id2))
+ );
+
+and you run:
+
+.. code-block:: none
+
+ $ build/dev/tools/scylla-sstable-index --type=Int32Type --type=UTF8Type --sstable /path/to/scylla/datadir/my_keyspace/my_table-1e13d620ea2811ebb808c477e839c4d7/md-1-big-Index.db
+
+the output would be:
+
+.. code-block:: none
+
+ 0: 3:third (pk{00040000000300057468697264})
+ 45: 2:second (pk{00040000000200067365636f6e64})
+ 91: 1:first (pk{00040000000100056669727374})
+
+.. tip:: Using the tool output you can use the raw Hex values to cross reference the :doc:`Scylla Logs </troubleshooting/log-level>` and find information on your SSTable.
\ No newline at end of file
diff --git a/docs/operating-scylla/admin-tools/sstable2json.rst b/docs/operating-scylla/admin-tools/sstable2json.rst
--- a/docs/operating-scylla/admin-tools/sstable2json.rst
+++ b/docs/operating-scylla/admin-tools/sstable2json.rst
@@ -0,0 +1,45 @@
+SSTable2json
+============
+
+
+This tool allows you to converts SSTable into a JSON format file.
+SSTable2json supported when using Scylla 2.x or lower version.
+In newer versions, the tool is named SSTabledump_.
+
+.. _SSTabledump: /operating-scylla/admin-tools/sstabledump
+
+.. note::
+
+ It is not recommended to use this tool in the production cluster.
+
+Use the full path when executing the command.
+
+For example:
+
+.. code-block:: shell
+
+ sstable2json /var/lib/scylla/data/keyspace1/standard1-7119946056b211e98e85000000000001
+
+Example output:
+
+.. code-block:: shell
+
+ [
+ {
+ "partition" : {
+ "key" : [ "3137343334334f4f4d30" ],
+ "position" : 0
+ },
+ "rows" : [
+ {
+ "type" : "static_block",
+ "position" : 281,
+ "cells" : [
+ { "name" : "\"C0\"", "value" : "0xb7789e7cdf2af541061f207714a3b8e14c72f74e663bd5c2577ac329bcb3161cf10c", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C1\"", "value" : "0xe8ed77f078a23e37f8a7246ccd8cd4099585c7031e242529e5070246860d7a1b1e85", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C2\"", "value" : "0x3b836d4333d2d5a02a63ced47596bfb5f80ecb8e80686061c3daaba87380994b7b61", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C3\"", "value" : "0x9220219581df87ff131306b8bf793c14ae8ebf8c8af1b638827ebfcab85660a378b8", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C4\"", "value" : "0x5b4c972cdeb330035b82dc0b1daa9051fff7956d45e3c6c2b21dfb1fd2bb43fb1146", "tstamp" : "2019-04-04T08:22:24.336001Z" }
+ ]
+ }
+ ]
diff --git a/docs/operating-scylla/admin-tools/sstabledump.rst b/docs/operating-scylla/admin-tools/sstabledump.rst
--- a/docs/operating-scylla/admin-tools/sstabledump.rst
+++ b/docs/operating-scylla/admin-tools/sstabledump.rst
@@ -0,0 +1,52 @@
+SSTabledump
+============
+
+This tool allows you to converts SSTable into a JSON format file.
+SSTabledump supported when using Scylla 3.0, Scylla Enterprise 2019.1, and newer versions.
+In older versions, the tool is named SSTable2json_.
+
+.. _SSTable2json: /operating-scylla/admin-tools/sstable2json
+
+Use the full path to the data file when executing the command.
+
+For example:
+
+.. code-block:: shell
+
+ sstabledump /var/lib/scylla/data/keyspace1/standard1-7119946056b211e98e85000000000001/mc-12-big-Data.db
+
+Example output:
+
+.. code-block:: shell
+
+ [
+ {
+ "partition" : {
+ "key" : [ "3137343334334f4f4d30" ],
+ "position" : 0
+ },
+ "rows" : [
+ {
+ "type" : "static_block",
+ "position" : 281,
+ "cells" : [
+ { "name" : "\"C0\"", "value" : "0xb7789e7cdf2af541061f207714a3b8e14c72f74e663bd5c2577ac329bcb3161cf10c", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C1\"", "value" : "0xe8ed77f078a23e37f8a7246ccd8cd4099585c7031e242529e5070246860d7a1b1e85", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C2\"", "value" : "0x3b836d4333d2d5a02a63ced47596bfb5f80ecb8e80686061c3daaba87380994b7b61", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C3\"", "value" : "0x9220219581df87ff131306b8bf793c14ae8ebf8c8af1b638827ebfcab85660a378b8", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C4\"", "value" : "0x5b4c972cdeb330035b82dc0b1daa9051fff7956d45e3c6c2b21dfb1fd2bb43fb1146", "tstamp" : "2019-04-04T08:22:24.336001Z" }
+ ]
+ }
+ ]
+
+
+
+**NOTE:**
+
+When running as a user that is not ``root`` or ``scylla`` an error (java traceback) might be observed.
+To work around the error, please use the following syntax:
+
+.. code-block:: sh
+
+ cassandra_storagedir="/tmp" sstabledump [filename]
+
diff --git a/docs/operating-scylla/admin-tools/sstableloader.rst b/docs/operating-scylla/admin-tools/sstableloader.rst
--- a/docs/operating-scylla/admin-tools/sstableloader.rst
+++ b/docs/operating-scylla/admin-tools/sstableloader.rst
@@ -0,0 +1,58 @@
+SSTableLoader
+=============
+
+Bulk load the sstables from a directory to a Scylla cluster via the **CQL API**.
+
+.. note::
+
+ This is **different** than Apache Cassandra tool with the same name, which uses internal RPC protocol to load the data.
+
+.. note::
+
+ sstableloader does **not** support loading from encrypted files. For restoring data from encrypted files see :ref:`Migration to Scylla <cassandra-to-scylla-procedure>`.
+
+
+SSTableLoader can be used to restore data from Scylla or Apache Cassandra backups or to clone data from cluster to cluster.
+It is especially useful, when the number of nodes, or token range distrbution between the source and target cluster are **not** the same. Since CQL API is used, Scylla will take care of distrbution the data.
+
+For example of such usage see :doc:`Apache Cassandra to Scylla Migration Process </operating-scylla/procedures/cassandra-to-scylla-migration-process>`
+
+usage: sstableloader [options] <dir_path>
+
+Bulk load the sstables found in the directory <dir_path> to the configured cluster. The parent directories of <dir_path> are used as the target ``keyspace/table`` name. So, for instance, to load an sstable named ``Standard1-g-1-Data.db`` into ``Keyspace1/Standard1``, you will need to have the files ``Standard1-g-1-Data.db`` and ``Standard1-g-1-Index.db`` into a directory ``/path/to/Keyspace1/Standard1/``.
+
+Parameters:
+
+* ``-alg,--ssl-alg <ALGORITHM>`` - Client SSL: algorithm (default: SunX509)
+* ``-bs,--batch-size <Number of bytes above which batch is being sent out>`` - Does not work with ``-nb``
+* ``-ciphers,--ssl-ciphers <CIPHER-SUITES>`` - Client SSL: comma-separated list of encryption suites to use
+* ``-cl,--consistency-level <consistency level (default: ONE)>`` - sets the consistency level for statements
+* ``-cph,--connections-per-host <connectionsPerHost>`` - number of concurrent connections-per-host.
+* ``-d,--nodes <initial hosts>`` - Required. try to connect to these hosts (comma separated) initially for ring information
+* ``-f,--conf-path <path to config file>`` - cassandra.yaml file path for streaming throughput and client/server SSL.
+* ``-g,--ignore-missing-columns <COLUMN NAMES...>`` - ignore named missing columns in tables
+* ``-h,--help`` - display this help message
+* ``-i,--ignore <NODES>`` - don't stream to this (comma separated) list of nodes
+* ``-ic,--ignore-dropped-counter-data`` - ignore dropping local and remote counter shard data
+* ``-ir,--no-infinite-retry`` - Disable infinite retry policy
+* ``-j,--threads-count <Number of threads to execute tasks>`` - Run tasks in parallel
+* ``-ks,--keystore <KEYSTORE>`` - Client SSL: full path to keystore
+* ``-kspw,--keystore-password <KEYSTORE-PASSWORD>`` - Client SSL: password of the keystore
+* ``-nb,--no-batch`` - Do not use batch statements updates for same partition key.
+* ``--no-progress`` - don't display progress
+* ``-nx,--no-prepared`` - Do not use prepared statements
+* ``-p,--port <port>`` - port used for connections (default 9042)
+* ``-prtcl,--ssl-protocol <PROTOCOL>`` - Client SSL: connections protocol to use (default: TLS)
+* ``-pt,--partitioner <class>`` - Partitioner type to use, defaults to cluster value
+* ``-pw,--password <password>`` - password for cassandra authentication
+* ``-s,--ssl <SSL>`` - Use SSL connection(s)
+* ``-sim,--simulate`` - simulate. Only print CQL generated
+* ``-st,--store-type <STORE-TYPE>`` - Client SSL: type of store
+* ``-t,--throttle <throttle>`` - throttle speed in Mbits (default unlimited)
+* ``-tr,--token-ranges <<lo>:<hi>,...>`` - import only partitions that satisfy lo < token(partition) <= hi
+* ``-translate,--translate <mapping list>`` - comma-separated list of column name mappings
+* ``-ts,--truststore <TRUSTSTORE>`` - Client SSL: full path to truststore
+* ``-tspw,--truststore-password <TRUSTSTORE-PASSWORD>`` - Client SSL: password of the truststore
+* ``--use-unset`` - Use 'unset' values in prepared statements
+* ``--username <username>`` - username for cassandra authentication
+* ``-v,--verbose <LEVEL>`` - verbose output
diff --git a/docs/operating-scylla/admin-tools/virtual-tables.rst b/docs/operating-scylla/admin-tools/virtual-tables.rst
--- a/docs/operating-scylla/admin-tools/virtual-tables.rst
+++ b/docs/operating-scylla/admin-tools/virtual-tables.rst
@@ -0,0 +1,15 @@
+===============
+Virtual Tables
+===============
+
+Virtual tables expose system-level information in the familiar CQL or Alternator interfaces.
+Virtual tables are not backed by physical storage (sstables) and generate their content on-the-fly when
+queried.
+
+ScyllaDB supports:
+
+* Virtual tables for retrieving system-level information, such as the cluster status, version-related information, etc. The range of information they can expose partially overlaps with the information you can obtain via :doc:`nodetool </operating-scylla/nodetool>` (unlike ``nodetool``, virtual tables permit remote access over CQL).
+* The virtual table for querying and updating configuration over CQL (the ``system.config`` table).
+
+See `Virtual tables in the system keyspace <https://github.com/scylladb/scylla/blob/branch-5.0/docs/design-notes/system_keyspace.md#virtual-tables-in-the-system-keyspace>`_ for the list of available virtual tables.
+
diff --git a/docs/operating-scylla/admin.rst b/docs/operating-scylla/admin.rst
--- a/docs/operating-scylla/admin.rst
+++ b/docs/operating-scylla/admin.rst
@@ -0,0 +1,273 @@
+Administration Guide
+********************
+
+For training material, also check out the `Admin Procedures lesson <https://university.scylladb.com/courses/scylla-operations/lessons/admin-procedures-and-basic-monitoring/>`_ on Scylla University.
+
+System requirements
+===================
+Make sure you have met the :doc:`System Requirements </getting-started/system-requirements>` before you install and configure Scylla.
+
+Download and Install
+====================
+
+See the :doc:`getting started page </getting-started/index>` for info on installing Scylla on your platform.
+
+
+System configuration
+====================
+See :ref:`System Configuration Guide <system-configuration-files-and-scripts>` for details on optimum OS settings for Scylla. (These settings are performed automatically in the Scylla packages, Docker containers, and Amazon AMIs.)
+
+.. _admin-scylla-configuration:
+
+Scylla Configuration
+====================
+Scylla configuration files are:
+
++-------------------------------------------------------+---------------------------------+
+| Installed location | Description |
++=======================================================+=================================+
+| :code:`/etc/default/scylla-server` (Ubuntu/Debian) | Server startup options |
+| :code:`/etc/sysconfig/scylla-server` (others) | |
++-------------------------------------------------------+---------------------------------+
+| :code:`/etc/scylla/scylla.yaml` | Main Scylla configuration file |
++-------------------------------------------------------+---------------------------------+
+| :code:`/etc/scylla/cassandra-rackdc.properties` | Rack & dc configuration file |
++-------------------------------------------------------+---------------------------------+
+
+.. _check-your-current-version-of-scylla:
+
+Check your current version of Scylla
+------------------------------------
+This command allows you to check your current version of Scylla. Note that this command is not the :doc:`nodetool version </operating-scylla/nodetool-commands/version>` command which reports the CQL version.
+If you are looking for the CQL or Cassandra version, refer to the CQLSH reference for :ref:`SHOW VERSION <cqlsh-show-version>`.
+
+.. code-block:: shell
+
+ scylla --version
+
+Output displays the Scylla version. Your results may differ.
+
+.. code-block:: shell
+
+ 4.4.0-0.20210331.05c6a40f0
+
+.. _admin-address-configuration-in-scylla:
+
+Address Configuration in Scylla
+-------------------------------
+
+The following addresses can be configured in scylla.yaml:
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Address Type
+ - Description
+ * - listen_address
+ - Address Scylla listens for connections from other nodes. See storage_port and ssl_storage_ports.
+ * - rpc_address
+ - Address on which Scylla is going to expect Thrift and CQL client connections. See rpc_port, native_transport_port and native_transport_port_ssl in the :ref:`Networking <cqlsh-networking>` parameters.
+ * - broadcast_address
+ - Address that is broadcasted to tell other Scylla nodes to connect to. Related to listen_address above.
+ * - broadcast_rpc_address
+ - Address that is broadcasted to tell the clients to connect to. Related to rpc_address.
+ * - seeds
+ - The broadcast_addresses of the existing nodes. You must specify the address of at least one existing node.
+ * - endpoint_snitch
+ - Node's address resolution helper.
+ * - api_address
+ - Address for REST API requests. See api_port in the :ref:`Networking <cqlsh-networking>` parameters.
+ * - prometheus_address
+ - Address for Prometheus queries. See prometheus_port in the :ref:`Networking <cqlsh-networking>` parameters and :doc:`Scylla Monitoring </operating-scylla/monitoring/index>` for more details.
+ * - replace_address_first_boot
+ - Address of the node this Scylla instance is meant to replace. Refer to :doc:`Replace a Dead Node in a Scylla Cluster </operating-scylla/procedures/cluster-management/replace-dead-node>` for more details.
+
+.. note:: When the listen_address, rpc_address, broadcast_address, and broadcast_rpc_address parameters are not set correctly, Scylla does not work as expected.
+
+scylla-server
+-------------
+The :code:`scylla-server` file contains configuration related to starting up the Scylla server.
+
+.. include:: /operating-scylla/scylla-yaml.inc
+
+Compression
+-----------
+
+In Scylla, you can configure compression at rest and compression in transit.
+For compression in transit, you can configure compression between nodes or between the client and the node.
+
+Client - Node Compression
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Compression between the client and the node is set by the driver that the application is using to access Scylla.
+
+For example:
+
+* `Scylla Python Driver <https://scylladb.github.io/python-driver/master/api/cassandra/cluster.html#cassandra.cluster.Cluster.compression>`_
+* `Scylla Java Driver <https://github.com/scylladb/java-driver/tree/3.7.1-scylla/manual/compression>`_
+* `Go Driver <https://godoc.org/github.com/gocql/gocql#Compressor>`_
+
+Refer to the :doc:`Drivers Page </using-scylla/drivers/index>` for more drivers.
+
+.. _internode-compression:
+
+Internode Compression
+^^^^^^^^^^^^^^^^^^^^^
+
+Internode compression is configured in the scylla.yaml
+
+internode_compression controls whether traffic between nodes is compressed.
+
+* all - all traffic is compressed.
+* dc - traffic between different datacenters is compressed.
+* none - nothing is compressed (default).
+
+Configuring TLS/SSL in scylla.yaml
+----------------------------------
+
+Scylla versions 1.1 and greater support encryption between nodes and between client and node. See the Scylla :doc:`Scylla TLS/SSL guide: </operating-scylla/security/index>` for configuration settings.
+
+.. _cqlsh-networking:
+
+Networking
+----------
+
+.. include:: /operating-scylla/_common/networking-ports.rst
+
+.. image:: /operating-scylla/security/Scylla-Ports2.png
+
+The Scylla ports are detailed in the table below. For Scylla Manager ports, see the `Scylla Manager Documentation <https://scylladb.github.io/scylla-manager>`_.
+
+.. include:: /operating-scylla/_common/networking-ports.rst
+
+All ports above need to be open to external clients (CQL), external admin systems (JMX), and other nodes (RPC). REST API port can be kept closed for incoming external connections.
+
+The JMX service, :code:`scylla-jmx`, runs on port 7199. It is required in order to manage Scylla using :code:`nodetool` and other Apache Cassandra-compatible utilities. The :code:`scylla-jmx` process must be able to connect to port 10000 on localhost. The JMX service listens for incoming JMX connections on all network interfaces on the system.
+
+Advanced networking
+-------------------
+It is possible that a client, or another node, may need to use a different IP address to connect to a Scylla node from the address that the node is listening on. This is the case when a node is behind port forwarding. Scylla allows for setting alternate IP addresses.
+
+Do not set any IP address to :code:`0.0.0.0`.
+
+.. list-table::
+ :widths: 30 40 30
+ :header-rows: 1
+
+ * - Address Type
+ - Description
+ - Default
+ * - listen_address (required)
+ - Address Scylla listens for connections from other nodes. See storage_port and ssl_storage_ports.
+ - No default
+ * - rpc_address (required)
+ - Address on which Scylla is going to expect Thrift and CQL clients connections. See rpc_port, native_transport_port and native_transport_port_ssl in the :ref:`Networking <cqlsh-networking>` parameters.
+ - No default
+ * - broadcast_address
+ - Address that is broadcasted to tell other Scylla nodes to connect to. Related to listen_address above.
+ - listen_address
+ * - broadcast_rpc_address
+ - Address that is broadcasted to tell the clients to connect to. Related to rpc_address.
+ - rpc_address
+
+
+If other nodes can connect directly to :code:`listen_address`, then :code:`broadcast_address` does not need to be set.
+
+If clients can connect directly to :code:`rpc_address`, then :code:`broadcast_rpc_address` does not need to be set.
+
+.. note:: For tips and examples on how to configure these addresses, refer to :doc:`How to Properly Set Address Values in scylla.yaml </kb/yaml-address>`
+
+.. _admin-core-dumps:
+
+Core dumps
+----------
+On RHEL and CentOS, the Automatic Bug Reporting Tool (`ABRT <https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/System_Administrators_Guide/ch-abrt.html>`_) conflicts with Scylla coredump configuration. Remove it before installing Scylla: :code:`sudo yum remove -y abrt`
+
+Scylla places any core dumps in :code:`var/lib/scylla/coredump`. They are not visible with the :code:`coredumpctl` command. See the :doc:`System Configuration Guide </getting-started/system-configuration/>` for details on core dump configuration scripts. Check with Scylla support before sharing any core dump, as they may contain sensitive data.
+
+
+Manual bootstrapping
+====================
+It’s possible to skip the bootstrapping process entirely and join the ring straight away by setting the hidden parameter ``auto_bootstrap: false``.
+A manual bootstrap node will skip the data stream phase and immediately join the cluster in a *UN* (Up Normal) state and start serving queries, even though it has no data.
+**It is firmly advised not to use Manual bootstrapping.**
+
+Note that starting a node as a seed, by including itself in the seeds list, has a similar effect of and it is similarly dangerous.
+
+See :doc:`Node Joined With No Data </troubleshooting/node-joined-without-any-data>` for troubleshooting a manually bootstrap node.
+
+Schedule fstrim
+===============
+
+Scylla sets up daily fstrim on the filesystem(s),
+containing your Scylla commitlog and data directory. This utility will
+discard, or trim, any blocks no longer in use by the filesystem.
+
+Experimental Features
+=====================
+
+Scylla Open Source uses experimental flags to expose non-production-ready features safely. These features are not stable enough to be used in production, and their API will likely change, breaking backward or forward compatibility.
+
+In recent Scylla versions, these features are controlled by the ``experimental_features`` list in scylla.yaml, allowing one to choose which experimental to enable.
+For example, some of the experimental features in Scylla Open Source 4.5 are: ``udf``, ``alternator-streams`` and ``raft``.
+Use ``scylla --help`` to get the list of experimental features.
+
+Scylla Enterprise and Scylla Cloud do not officially support experimental Features.
+
+Monitoring
+==========
+Scylla exposes interfaces for online monitoring, as described below.
+
+Monitoring Interfaces
+---------------------
+
+`Scylla Monitoring Interfaces <https://monitoring.docs.scylladb.com/stable/reference/monitoring_apis.html>`_
+
+Monitoring Stack
+----------------
+
+|mon_root|
+
+JMX
+---
+Scylla JMX is compatible with Apache Cassandra, exposing the relevant subset of MBeans.
+
+.. REST
+
+.. include:: /operating-scylla/rest.rst
+
+Un-contents
+-----------
+
+Scylla is designed for high performance before tuning, for fewer layers that interact in unpredictable ways, and to use better algorithms that do not require manual tuning. The following items are found in the manuals for other data stores but do not need to appear here.
+
+Configuration un-contents
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Generating tokens
+* Configuring virtual nodes
+
+Operations un-contents
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Tuning Bloom filters
+* Data caching
+* Configuring memtable throughput
+* Configuring compaction
+* Compression
+
+Testing compaction and compression
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Tuning Java resources
+* Purging gossip state on a node
+
+
+Help with Scylla
+================
+Contact `Support <https://www.scylladb.com/product/support/>`_, or visit the Scylla `Community <https://www.scylladb.com/open-source-community/>`_ page for peer support.
+
+.. include:: /rst_include/apache-copyrights-index.rst
+
+.. include:: /rst_include/apache-copyrights-index-all-attributes.rst
diff --git a/docs/operating-scylla/benchmarking-scylla.rst b/docs/operating-scylla/benchmarking-scylla.rst
--- a/docs/operating-scylla/benchmarking-scylla.rst
+++ b/docs/operating-scylla/benchmarking-scylla.rst
@@ -0,0 +1,9 @@
+===================
+Benchmarking Scylla
+===================
+
+
+For more information on the best way to benchmark Scylla, check out our blog:
+
+* `Best Practices for Benchmarking Scylla <https://www.scylladb.com/2021/03/04/best-practices-for-benchmarking-scylla/>`_
+* `How to Test and Benchmark Database Clusters <https://www.scylladb.com/2020/11/04/how-to-test-and-benchmark-database-clusters/>`_
diff --git a/docs/operating-scylla/gcsnitch.png b/docs/operating-scylla/gcsnitch.png
--- a/docs/operating-scylla/gcsnitch.png
+++ b/docs/operating-scylla/gcsnitch.png
null
diff --git a/docs/operating-scylla/index.rst b/docs/operating-scylla/index.rst
--- a/docs/operating-scylla/index.rst
+++ b/docs/operating-scylla/index.rst
@@ -0,0 +1,57 @@
+Scylla for Administrators
+=========================
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ admin
+ Procedures <procedures/index>
+ security/index
+ admin-tools/index
+ manager/index
+ Scylla Monitoring Stack <monitoring/index>
+ Scylla Operator <scylla-operator/index>
+ Upgrade Procedures </upgrade/index>
+ System Configuration <system-configuration/index>
+ benchmarking-scylla
+
+.. panel-box::
+ :title: Scylla Administration
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Administrator Guide </operating-scylla/admin/>` - Guide for Scylla Administration
+ * :doc:`Upgrade Scylla </upgrade/index>` - Upgrade Procedures for all Scylla Products and Versions
+ * :doc:`System Configuration </operating-scylla/system-configuration/index>` - Information on the Scylla configuration files
+ * :doc:`Procedures </operating-scylla/procedures/index>` - Procedures to create, out-scale, down-scale, and backup Scylla clusters
+ * :doc:`Scylla Security </operating-scylla/security/index>` - Procedures to secure, authenticate, and encrypt Scylla users and data
+
+.. panel-box::
+ :title: Scylla Tools
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Tools </operating-scylla/admin-tools/index>` - Tools for Administrating and integrating with Scylla
+ * :doc:`Scylla Manager </operating-scylla/manager/index>` - Tool for cluster administration and automation
+ * :doc:`Scylla Monitoring Stack </operating-scylla/monitoring/index>` - Tool for cluster monitoring and alerting
+ * :doc:`Scylla Operator </operating-scylla/scylla-operator/index>` - Tool to run Scylla on Kubernetes
+ * :doc:`Scylla Logs </getting-started/logging/>`
+
+.. panel-box::
+ :title: Benchmark Testing
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Benchmark Testing for Scylla </operating-scylla/benchmarking-scylla/>` - Information on benchmark tests you can conduct on Scylla
+
+.. panel-box::
+ :title: Learn More About Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Learn To Use Scylla </using-scylla/learn>` - Scylla University offers many courses. Pick a course and get started on your path to becoming a Scylla expert.
+ * :doc:`Scylla Features </using-scylla/features>` - Feature list for Scylla Open Source and Scylla Enterprise
+
+
+
diff --git a/docs/operating-scylla/manager/2.1/_common/cluster-params.rst b/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
--- a/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
+++ b/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
@@ -0,0 +1,40 @@
+``--host <node IP>``
+
+Specifies the hostname or IP of the node that will be used to discover other nodes belonging to the cluster.
+Note that this will be persisted and used every time Scylla Manager starts. You can use either an IPv4 or IPv6 address.
+
+=====
+
+``-n, --name <alias>``
+
+When a cluster is added, it is assigned a unique identifier.
+Use this parameter to identify the cluster by an alias name which is more meaningful.
+This alias name can be used with all commands that accept ``-c, --cluster`` parameter.
+
+=====
+
+``--auth-token <token>``
+
+Specifies the :ref:`authentication token <manager-2.1-generate-auth-token>` you identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+=====
+
+``-u, --username <cql username>``
+
+Optional CQL username, for security reasons this user should NOT have access to your data.
+If you specify the CQL username and password, the CQL health check you see in `status`_ would try to login and execute a query against system keyspace.
+Otherwise CQL health check is based on sending `CQL OPTIONS frame <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec#L302>`_ and does not start a CQL session.
+
+=====
+
+``-p, --password <password>``
+
+CQL password associated with username.
+
+=====
+
+``--without-repair``
+
+When cluster is added, Manager schedules repair to repeat every 7 days. To create a cluster without a scheduled repair, use this flag.
+
+
diff --git a/docs/operating-scylla/manager/2.1/_common/glob.rst b/docs/operating-scylla/manager/2.1/_common/glob.rst
--- a/docs/operating-scylla/manager/2.1/_common/glob.rst
+++ b/docs/operating-scylla/manager/2.1/_common/glob.rst
@@ -0,0 +1,10 @@
+The following syntax is supported:
+
+* ``*`` - matches any number of any characters including none
+* ``?`` - matches any single character
+* ``[abc]`` - matches one character given in the bracket
+* ``[a-z]`` - matches one character from the range given in the bracket
+
+Patterns are evaluated from left to right.
+If a pattern starts with ``!`` it unselects items that were selected by previous patterns
+i.e. ``a?,!aa`` selects *ab* but not *aa*.
diff --git a/docs/operating-scylla/manager/2.1/_common/manager-description.rst b/docs/operating-scylla/manager/2.1/_common/manager-description.rst
--- a/docs/operating-scylla/manager/2.1/_common/manager-description.rst
+++ b/docs/operating-scylla/manager/2.1/_common/manager-description.rst
@@ -0,0 +1,6 @@
+Scylla Manager is a product for database operations automation, it can schedule tasks such as repairs and backups.
+Scylla Manager can manage multiple Scylla clusters and run cluster-wide tasks in a controlled and predictable way.
+
+Scylla Manager is available for Scylla Enterprise customers and Scylla Open Source users.
+With Scylla Open Source, Scylla Manager is limited to 5 nodes.
+See the Scylla Manager Proprietary Software `License Agreement <https://www.scylladb.com/scylla-manager-software-license-agreement/>`_ for details.
diff --git a/docs/operating-scylla/manager/2.1/_common/param-cluster.rst b/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
--- a/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
+++ b/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
@@ -0,0 +1,3 @@
+``-c`` , ``--cluster``
+
+This is the cluster name is the name you assigned when you created the cluster (`cluster add`_). You can see the cluster name and ID by running the command `cluster list`_.
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/2.1/_common/task-id-note.rst b/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
--- a/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
+++ b/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
@@ -0,0 +1,3 @@
+A task ID with a type (repair, for example) is **required** for this command.
+This is a unique ID which is created when the task was made.
+To display the ID, run the command ``sctool task list`` (see `task list`_).
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/2.1/_common/task-params.rst b/docs/operating-scylla/manager/2.1/_common/task-params.rst
--- a/docs/operating-scylla/manager/2.1/_common/task-params.rst
+++ b/docs/operating-scylla/manager/2.1/_common/task-params.rst
@@ -0,0 +1,41 @@
+``--interval <time between task runs>``
+
+Amount of time after which a successfully completed task would be run again.
+Supported time units include:
+
+* ``d`` - days,
+* ``h`` - hours,
+* ``m`` - minutes,
+* ``s`` - seconds.
+
+**Default** 0 (no interval)
+
+.. note:: The task run date is aligned with ``--start date`` value. For example, if you select ``--interval 7d`` task would run weekly at the ``--start-date`` time.
+
+=====
+
+``-s, --start-date <now+duration|RFC3339>``
+
+The date can be expressed relatively to now or as a RFC3339 formatted string.
+To run the task in 2 hours use ``now+2h``, supported units are:
+
+* ``h`` - hours,
+* ``m`` - minutes,
+* ``s`` - seconds,
+* ``ms`` - milliseconds.
+
+If you want the task to start at a specified date use RFC3339 formatted string i.e. ``2018-01-02T15:04:05-07:00``.
+If you want the repair to start immediately, use the value ``now`` or skip this flag.
+
+**Default:** now (start immediately)
+
+=====
+
+``-r, --num-retries <times to rerun a failed task>``
+
+Number of times a task reruns following a failure. The task reruns 10 minutes following a failure.
+If the task fails after the retry times have been used, it will not retry again until its next run which was scheduled according to the ``--interval`` parameter.
+
+.. note:: If this is an ad hoc repair, the task will not run again.
+
+**Default:** 3
diff --git a/docs/operating-scylla/manager/2.1/add-a-cluster.rst b/docs/operating-scylla/manager/2.1/add-a-cluster.rst
--- a/docs/operating-scylla/manager/2.1/add-a-cluster.rst
+++ b/docs/operating-scylla/manager/2.1/add-a-cluster.rst
@@ -0,0 +1,162 @@
+=========================================
+Add a cluster or a node to Scylla Manager
+=========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+Scylla Manager manages clusters. A cluster contains one or more nodes / datacenters. When you add a cluster to Scylla Manager, it adds all of the nodes which are:
+
+* associated with it,
+* that are running Scylla Manager Agent,
+* and are accessible
+
+
+Port Settings
+=============
+
+Confirm all ports required for Scylla Manager and Scylla Manager Agent are open. This includes:
+
+* 9042 CQL
+* 9142 SSL CQL
+* 10001 Scylla Agent REST API
+
+
+Add a Cluster
+=============
+
+This procedure adds the nodes to Scylla Manager so the cluster can be a managed cluster under Scylla Manager.
+
+Prerequisites
+-------------
+
+For each node in the cluster, the **same** :ref:`authentication token <manager-2.1-generate-auth-token>` needs to be identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+Create a Managed Cluster
+------------------------
+
+.. _name:
+
+**Procedure**
+
+#. From the Scylla Manager Server, provide the broadcast_address of one of the nodes and the generated auth_token (if used) and a custom name if desired.
+
+ Where:
+
+ * ``--host`` is hostname or IP of one of the cluster nodes. You can use an IPv6 or an IPv4 address.
+ * ``--name`` is an alias you can give to your cluster. Using an alias means you do not need to use the ID of the cluster in all other operations.
+ * ``--auth-token`` is the authentication :ref:`token <manager-2.1-generate-auth-token>` you identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+ * ``--without-repair`` - when a cluster is added, the Manager schedules repair to repeat every 7 days. To create a cluster without a scheduled repair, use this flag.
+ * ``--username`` and ``--password`` - optionally, you can provide CQL credentials to the cluster.
+ For security reasons, the user should NOT have access to your data.
+ This enables :ref:`CQL query-based health check <manager-2.1-cql-query-health-check>` compared to :ref:`credentials agnostic health check <manager-2.1-credentials-agnostic-health-check>` if you do not specify the credentials.
+ This also enables CQL schema backup, which isn't performed if credentials aren't provided.
+
+ Example (IPv4):
+
+ .. code-block:: none
+
+ sctool cluster add --host 34.203.122.52 --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+ c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ __
+ / \ Cluster added! You can set it as default by exporting env variable.
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ | | $ export SCYLLA_MANAGER_CLUSTER=prod-cluster
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c prod-cluster
+ \___/ $ sctool task list -c prod-cluster
+
+
+ Example (IPv6):
+
+ .. code-block:: none
+
+ sctool cluster add --host 2a05:d018:223:f00:971d:14af:6418:fe2d --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+ Each cluster has a unique ID.
+ You will use this ID in all commands where the cluster ID is required.
+ Each cluster is automatically registered with a repair task that runs once a week.
+ This can be canceled using ``--without-repair``.
+ To use a different repair schedule, see :ref:`Schedule a Repair <manager-2.1-schedule-a-repair>`.
+
+#. Verify that the cluster you added has a registered repair task by running the ``sctool task list -c <cluster-name>`` command, adding the name_ of the cluster you created in step 1 (with the ``--name`` flag).
+
+ .. code-block:: none
+
+ sctool task list -c prod-cluster
+ ╭───────────────────────────────────────────────────────┬───────────┬────────────────────────────────┬────────╮
+ │ Task │ Arguments │ Next run │ Status │
+ ├───────────────────────────────────────────────────────┼───────────┼────────────────────────────────┼────────┤
+ │ healthcheck/8988932e-de2f-4c42-a2f8-ae3b97fd7126 │ │ 02 Apr 20 12:28:10 CEST (+15s) │ NEW │
+ │ healthcheck_rest/9b7e694d-a1e3-42f1-8ca6-d3dfd9f0d94f │ │ 02 Apr 20 12:28:40 CEST (+1h) │ NEW │
+ │ repair/0fd8a43b-eacf-4df8-9376-2a31b0dee6cc │ │ 03 Apr 20 00:00:00 CEST (+7d) │ NEW │
+ ╰───────────────────────────────────────────────────────┴───────────┴────────────────────────────────┴────────╯
+
+ You will see 3 tasks which are created by adding the cluster:
+
+ * Healthcheck - which checks the Scylla CQL, starting immediately, repeating every 15 seconds. See `Scylla Health Check <../health-check>`_
+ * Healthcheck REST - which checks the Scylla REST API, starting immediately, repeating every hour. See `Scylla Health Check <../health-check>`_
+ * Repair - an automated repair task, starting at midnight tonight, repeating every seven days at midnight. See `Run a Repair <../repair/>`_
+
+ .. note:: If you want to change the schedule for the repair, see :ref:`Reschedule a repair <manager-2.1-reschedule-a-repair>`.
+
+Connect Managed Cluster to Scylla Monitoring
+============================================
+
+Connecting your cluster to Scylla Monitoring allows you to see metrics about your cluster and Scylla Manager all within Scylla Monitoring.
+
+To connect your cluster to Scylla Monitoring, it is **required** to use the same cluster name_ as you used when you created the cluster. See `Add a Cluster`_.
+
+**Procedure**
+
+Follow the procedure |mon_root| as directed, remembering to update the Scylla Node IPs and Cluster name_ as well as the Scylla Manager IP in the relevant Prometheus configuration files.
+
+If you have any issues connecting to Scylla Monitoring Stack, consult the :doc:`Troubleshooting Guide </troubleshooting/manager-monitoring-integration>`.
+
+Add a Node to a Managed Cluster
+===============================
+
+Although Scylla Manager is aware of all topology changes made within every cluster it manages, it cannot properly manage nodes/datacenters without establishing connections with every node/datacenter in the cluster, including the Scylla Manager Agent, which is on each managed node.
+
+**Before You Begin**
+
+* Confirm you have a managed cluster running under Scylla Manager. If you do not have a managed cluster, see `Add a cluster`_.
+* Confirm the :ref:`node <add-node-to-cluster-procedure>` or :doc:`Datacenter </operating-scylla/procedures/cluster-management/add-dc-to-existing-dc>` is added to the Scylla Cluster.
+
+**Procedure**
+
+#. `Add Scylla Manager Agent <../install-agent>`_ to the new node. Use the **same** authentication token as you did for the other nodes in this cluster. Do not generate a new token.
+
+#. Confirm the node / datacenter was added by checking its :ref:`status <sctool_status>`. From the node running the Scylla Manager server, run the ``sctool status`` command, using the name of the managed cluster.
+
+ .. code-block:: none
+
+ sctool status -c prod-cluster
+ Datacenter: eu-west
+ ╭────┬───────────────┬────────────┬──────────────┬──────────────────────────────────────╮
+ │ │ CQL │ REST │ Host │ Host ID │
+ ├────┼───────────────┼────────────┼──────────────┼──────────────────────────────────────┤
+ │ UN │ UP SSL (42ms) │ UP (52ms) │ 10.0.114.68 │ 45a7390d-d162-4daa-8bff-6469c9956f8b │
+ │ UN │ UP SSL (38ms) │ UP (88ms) │ 10.0.138.46 │ 8dad7fc7-5a82-4fbb-8901-f6f60c12342a │
+ │ UN │ UP SSL (38ms) │ UP (298ms) │ 10.0.196.204 │ 44eebe5b-e0cb-4e45-961f-4ad175592977 │
+ │ UN │ UP SSL (43ms) │ UP (159ms) │ 10.0.66.115 │ 918a52aa-cc42-43a4-a499-f7b1ccb53b18 │
+ ╰────┴───────────────┴────────────┴──────────────┴──────────────────────────────────────╯
+
+#. If you are using the Scylla Monitoring Stack, continue to `Connect Managed Cluster to Scylla Monitoring`_ for more information.
+
+Remove a Node/Datacenter from Scylla Manager
+--------------------------------------------
+
+There is no need to perform any action in Scylla Manager after removing a node or datacenter from a Scylla cluster.
+
+.. note:: If you are removing the cluster from Scylla Manager and you are using Scylla Monitoring, refer to |mon_root| for more information.
+
+See Also
+========
+
+* `sctool Reference <../sctool>`_
+* :doc:`Remove a node from a Scylla Cluster </operating-scylla/procedures/cluster-management/remove-node>`
+* :doc:`Scylla Monitoring </operating-scylla/monitoring/index>`
+
diff --git a/docs/operating-scylla/manager/2.1/agent-configuration-file.rst b/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
--- a/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
+++ b/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
@@ -0,0 +1,205 @@
+========================
+Agent Configuration File
+========================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+
+This document covers the configurations settings you need to consider for the Sylla Manager Agent.
+
+The Scylla Manager Agent has a single configuration file /etc/scylla-manager-agent/scylla-manager-agent.yaml.
+
+.. _manger-2.1-agent-configuration-file-auth-token:
+
+Authentication token
+====================
+
+.. note:: Completing this section in the scylla-manager-agent.yaml file is mandatory
+
+Scylla Agent uses token authentication in API calls so that the Scylla Manager Server can authenticate itself with the Scylla Manager Agent.
+Once you have :ref:`created a token <manager-2.1-generate-auth-token>`, and have configured the :ref:`agent configuration file <manager-2.1-configure-auth-token>` as described.
+
+.. code-block:: none
+
+ # Specify authentication token
+ auth_token: 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+HTTPS server settings
+=====================
+
+In this section, you can specify which address Scylla Agent should listen to.
+By default, Scylla Manager Agent pulls these values from the Scylla itself.
+Port 10001 is the default port, and traffic to this port should be allowed on the firewall.
+You can change the port to a different port by clearing the ``https`` label and adding an IP address and port.
+In order to obtain TLS cert and key file, use the ``scyllamgr_ssl_cert_gen`` script.
+
+.. code-block:: none
+
+ # Bind REST API to the specified TCP address using HTTPS protocol. By default
+ # Scylla Manager Agent uses Scylla listen/broadcast address that is read from
+ # the Scylla API (see the scylla section).
+ #https: 0.0.0.0:10001
+
+ # TLS certificate and key files to use with HTTPS. To regenerate the files use
+ # scyllamgr_ssl_cert_gen script shipped with the Scylla Manager Agent.
+ #tls_cert_file: /var/lib/scylla-manager/scylla_manager.crt
+ #tls_key_file: /var/lib/scylla-manager/scylla_manager.key
+
+Prometheus settings
+===================
+
+In this section, you can set the Prometheus settings for the Scylla Manager Agent so that the Agent Manager metrics (from each Sylla node) can be viewed and monitored with Scylla Monitoring.
+
+.. code-block:: none
+
+ # Bind Prometheus API to the specified TCP address using HTTP protocol.
+ # By default it binds to all network interfaces, but you can restrict it
+ # by specifying it like this 127:0.0.1:56090 or any other combination
+ # of ip and port.
+ #prometheus: ':56090'
+
+If you change the Prometheus IP or port, you must adjust the rules in the Prometheus server.
+
+.. code-block:: none
+
+ - targets:
+ - IP:56090
+
+Debug endpoint settings
+=======================
+
+In this section, you can specify the pprof debug server address.
+It allows you to run profiling on demand on a live application.
+By default, the server is running on port ``56112``.
+
+.. code-block:: none
+
+ debug: 127.0.0.1:56112
+
+CPU pinning settings
+====================
+
+In this section, you can set the ``cpu`` setting, which dictates the CPU to run Scylla Manager Agent on.
+By default, the agent reads the Scylla configuration from ``/etc/scylla.d/cpuset.conf`` and tries to find a core that is not used by Scylla.
+If that's not possible, you can specify the core on which to run the Scylla Manager Agent.
+
+.. code-block:: none
+
+ cpu: 0
+
+Log level settings
+==================
+
+In this section, you can set the Log level settings which specify log output and level. Available log levels are ``error``, ``info`` and ``debug``.
+
+.. code-block:: none
+
+ logger:
+ level: info
+
+Scylla API settings
+===================
+
+In this section, you can set the Scylla API settings. Scylla Manager Agent pulls all needed configuration options from the ``scylla.yaml`` file. In order to do this, Scylla Manager Agent needs to know where the Scylla API is exposed. You should copy the ``api_address`` and ``api_port`` values from ``/etc/scylla/scylla.yaml`` and add them here:
+
+.. code-block:: none
+
+ #scylla:
+ # api_address: 0.0.0.0
+ # api_port: 10000
+
+Backup S3 settings
+==================
+
+In this section, you configure the AWS credentials (if required) for the backup location.
+
+IAM Role
+--------
+
+.. note:: If you are setting an IAM role in AWS, you do not need to change this section.
+
+.. _manager-2.1-aws-credentials:
+
+AWS credentials
+---------------
+
+.. note:: Completing this section in the scylla-manager-agent.yaml file is mandatory if you are not using an IAM role. Make sure you understand the security ramifications of placing AWS credentials into the yaml file.
+
+Fill in the information below with your AWS Credentials information.
+If you do not know where your keys are located, read the `AWS Security Blogs <https://aws.amazon.com/blogs/security/wheres-my-secret-access-key/>`_ or `documentation <https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys>`_ for information.
+
+.. code-block:: none
+
+ s3:
+ # S3 credentials, it's recommended to use IAM roles if possible, otherwise set
+ # your AWS Access Key ID and AWS Secret Access Key (password) here.
+ access_key_id: <your access key id>
+ secret_access_key: <your secret access key>
+
+MinIO and other AWS S3 alternatives
+-----------------------------------
+
+Backup can work with MinIO and other AWS S3 compatible providers.
+The available options are:
+
+* Alibaba,
+* Ceph,
+* DigitalOcean,
+* IBMCOS,
+* Minio,
+* Wasabi,
+* Dreamhost,
+* Netease.
+
+To configure S3 with a 3rd-party provider, in addition to credentials, one needs to specify ``provider`` parameter with one of the above options.
+If the service is self-hosted, it's also needed to specify ``endpoint`` with its base URL address.
+
+.. code-block:: none
+
+ s3:
+ # S3 credentials, it's recommended to use IAM roles if possible, otherwise set
+ # your AWS Access Key ID and AWS Secret Access Key (password) here.
+ access_key_id: <your access key id>
+ secret_access_key: <your secret access key>
+ # Provider of the S3 service. By default, this is AWS. There are multiple S3
+ # API compatible providers that can be used instead. Due to minor differences
+ # between them we require that exact provider is specified here for full
+ # compatibility. Supported and tested options are: AWS and Minio.
+ # The available providers are: Alibaba, AWS, Ceph, DigitalOcean, IBMCOS, Minio,
+ # Wasabi, Dreamhost, Netease.
+ provider: Minio
+ #
+ # Endpoint for S3 API, only relevant when using S3 compatible API.
+ endpoint: <your MinIO instance URL>
+
+Advanced settings
+-----------------
+
+.. code-block:: none
+
+ #s3:
+ # The server-side encryption algorithm used when storing this object in S3.
+ # If using KMS ID you must provide the ARN of Key.
+ # server_side_encryption:
+ # sse_kms_key_id:
+ #
+ # Number of files uploaded concurrently, by default it's 2.
+ # upload_concurrency: 2
+ #
+ # Maximum size (in bytes) of the body of a single request to S3 when uploading big files.
+ # Big files are cut into chunks. This value allows specifying how much data
+ # single request to S3 can carry. Bigger value allows reducing the number of requests
+ # needed to upload files, increasing it may help with 5xx responses returned by S3.
+ # Default value is 50M, and the string representation of the value can be provided, for
+ # e.g. 1M, 1G, off.
+ # chunk_size: 50M
+ #
+ # AWS S3 Transfer acceleration
+ # https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration-examples.html
+ # use_accelerate_endpoint: false
+
+Additional resources
+====================
+
+Scylla Manager `Configuration file <../configuration-file>`_
diff --git a/docs/operating-scylla/manager/2.1/architecture.jpg b/docs/operating-scylla/manager/2.1/architecture.jpg
--- a/docs/operating-scylla/manager/2.1/architecture.jpg
+++ b/docs/operating-scylla/manager/2.1/architecture.jpg
null
diff --git a/docs/operating-scylla/manager/2.1/architecture.png b/docs/operating-scylla/manager/2.1/architecture.png
--- a/docs/operating-scylla/manager/2.1/architecture.png
+++ b/docs/operating-scylla/manager/2.1/architecture.png
null
diff --git a/docs/operating-scylla/manager/2.1/architecture.rst b/docs/operating-scylla/manager/2.1/architecture.rst
--- a/docs/operating-scylla/manager/2.1/architecture.rst
+++ b/docs/operating-scylla/manager/2.1/architecture.rst
@@ -0,0 +1,57 @@
+============
+Architecture
+============
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager is a product for database operations automation.
+It can manage multiple Scylla clusters and run cluster-wide tasks in a controlled and predictable way.
+Scylla Manager discovers cluster topology and is aware of nodes belonging to different datacenters.
+
+Deployment
+==========
+
+Scylla Manager consists of three components:
+
+* Server - a daemon that exposes REST API
+* sctool - a command-line interface (CLI) for interacting with the Server over the REST API
+* Agent - a small executable, installed on each Scylla node. The Server communicates with the Agent over REST HTTPS. The Agent communicates with the local Scylla node over the REST HTTP.
+
+The Server persists its data to a Scylla cluster that can run locally or run on an external cluster
+(see `Use a remote database for Scylla Manager <../use-a-remote-db>`_ for details).
+
+Optionally (but recommended), you can add Scylla Monitoring Stack to enable reporting of Scylla Manager metrics and alerts.
+
+The diagram below presents a logical view of Scylla Manager with a remote backend datastore managing multiple Scylla Clusters situated in datacenters.
+
+
+Each node has two connections with the Scylla Manager Server:
+
+* REST API connection - used for Scylla Manager and Scylla Manager Agent activities
+* CQL connection - used for the Scylla `Health Check <../health-check>`_
+
+Scylla Manager uses the following ports:
+
+====== ============================================ ========
+Port Description Protocol
+====== ============================================ ========
+10001 Scylla Manager Agent REST API TCP
+------ -------------------------------------------- --------
+56080 Scylla Manager HTTP (default) HTTP
+------ -------------------------------------------- --------
+56443 Scylla Manager HTTPS (default) HTTPS
+------ -------------------------------------------- --------
+56090 Scylla Manager Prometheus API HTTP
+------ -------------------------------------------- --------
+56090 Scylla Manager Agent Prometheus API TCP
+====== ============================================ ========
+
+
+.. image:: architecture.png
+
+Additional Resources
+====================
+
+* `Install Scylla Manager <../install>`_
+* `Install Scylla Manager Agent <../install-agent>`_
+* `sctool Reference <../sctool>`_
diff --git a/docs/operating-scylla/manager/2.1/backup.rst b/docs/operating-scylla/manager/2.1/backup.rst
--- a/docs/operating-scylla/manager/2.1/backup.rst
+++ b/docs/operating-scylla/manager/2.1/backup.rst
@@ -0,0 +1,330 @@
+======
+Backup
+======
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Using sctool, you can backup and restore your managed Scylla clusters under Scylla Manager.
+Backups are scheduled in the same manner as repairs. You can start, stop, and track backup operations on demand.
+Scylla Manager can backup to Amazon S3 and S3 compatible API storage providers such as Ceph or MinIO.
+
+
+Benefits of using Scylla Manager backups
+========================================
+
+Scylla Manager automates the backup process and allows you to configure how and when a backup occurs.
+The advantages of using Scylla Manager for backup operations are:
+
+* Data selection - backup a single table or an entire cluster, the choice is up to you
+* Data deduplication - prevents multiple uploads of the same SSTable
+* Data retention - purge old data automatically when all goes right, or failover when something goes wrong
+* Data throttling - control how fast you upload or Pause/resume the backup
+* Lower disruption to the workflow of the Scylla Manager Agent due to cgroups and/or CPU pinning
+* No cross-region traffic - configurable upload destination per datacenter
+
+The backup process
+==================
+
+The backup procedure consists of multiple steps executed sequentially.
+It runs parallel on all nodes unless you limit it with the ``--snapshot-parallel`` or ``--upload-parallel`` :ref:`flag <sctool-backup-parameters>`.
+
+#. **Snapshot** - Take a :term:`snapshot <Snapshot>` of data on each node (according to backup configuration settings).
+#. **Schema** - (Optional) Upload the schema CQL to the backup storage destination, this requires that you added the cluster with ``--username`` and ``--password`` flags. See :doc:`Add Cluster <add-a-cluster>` for reference.
+#. **Upload** - Upload the snapshot to the backup storage destination.
+#. **Manifest** - Upload the manifest file containing metadata about the backup.
+#. **Purge** - If the retention threshold has been reached, remove the oldest backup from the storage location.
+
+Prepare nodes for backup
+========================
+
+#. Create a storage location for the backup.
+ Currently, Scylla Manager supports `Amazon S3 buckets <https://aws.amazon.com/s3/>`_ .
+ You can use an S3 bucket that you already created.
+ We recommend using an S3 bucket in the same region where your nodes are to minimize cross-region data transfer costs.
+ In multi-dc deployments, you should create a bucket per datacenter, each located in the datacenter's region.
+#. Choose how you want to configure access to the S3 Bucket.
+ You can use an IAM role (recommended), or you can add your AWS credentials to the agent configuration file.
+ The latter method is less secure as you will be propagating each node with this security information, and in cases where you need to change the key, you will have to replace it on each node.
+
+**To use an IAM Role**
+
+#. Create an `IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html>`_ for the S3 bucket which adheres to your company security policy.
+#. `Attach the IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html#attach-iam-role>`_ to **each EC2 instance (node)** in the cluster.
+
+Sample IAM policy for *scylla-manager-backup* bucket:
+
+.. code-block:: none
+
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:GetBucketLocation",
+ "s3:ListBucket",
+ "s3:ListBucketMultipartUploads"
+ ],
+ "Resource": [
+ "arn:aws:s3:::scylla-manager-backup"
+ ]
+ },
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:PutObject",
+ "s3:GetObject",
+ "s3:DeleteObject",
+ "s3:AbortMultipartUpload",
+ "s3:ListMultipartUploadParts"
+ ],
+ "Resource": [
+ "arn:aws:s3:::scylla-manager-backup/*"
+ ]
+ }
+ ]
+ }
+
+**To add your AWS credentials the Scylla Manager Agent configuration file**
+
+Edit the ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+#. Uncomment the ``s3:`` line, for parameters, note the two spaces in front, it's a yaml file.
+#. Uncomment and set ``access_key_id`` and ``secret_access_key``, refer to :ref:`AWS Credentials Configuration <manager-2.1-aws-credentials>` for details.
+#. If NOT running in AWS EC2 instance, uncomment and set ``region`` to a region where you created the S3 bucket.
+
+Troubleshooting
+---------------
+
+To troubleshoot Node to S3 connectivity issues, you can run:
+
+.. code-block:: none
+
+ scylla-manager-agent check-location --debug --location s3:<your S3 bucket name>
+
+Schedule a backup
+=================
+
+The most recommended way to run a backup is across an entire cluster.
+Backups can be scheduled to run on single or multiple datacenters, keyspaces, or tables.
+The backup procedure can be customized, allowing you to plan your backups according to your IT policy.
+All parameters can be found in the :ref:`sctool reference <sctool-backup>`.
+If you want to check if all of your nodes can connect to the backup storage location, see `Perform a Dry Run of a Backup`_.
+
+**Prerequisites**
+
+#. Backup locations (S3 buckets) created.
+#. Access rights to backup locations granted to Nodes, see `Prepare Nodes for Backup`_.
+
+Create a scheduled backup
+-------------------------
+
+Use the example below to run the sctool backup command.
+
+.. code-block:: none
+
+ sctool backup -c <id|name> -L <list of locations> [-s <date>] [-i <time-unit>]
+
+where:
+
+* ``-c`` - the :ref:`name <sctool-cluster-add>` you used when you created the cluster
+* ``-L`` - points to backup storage location in ``s3:<your S3 bucket name>`` format or ``<your DC name>:s3:<your S3 bucket name>`` if you want to specify a location for a datacenter
+* ``-s`` - the time you want the backup to begin
+* ``-i`` - the time interval you want to use in between consecutive backups
+
+If you want to run the backup only once, see `Create an ad-hoc backup`_.
+In case when you want the backup to start immediately, but you want it to schedule it to repeat at a determined interval, leave out the start flag (``-s``) and set the interval flag (``-i``) to the time you want the backup to reoccur.
+
+Schedule a daily backup
+.......................
+
+This command will schedule a backup on 9th Dec 2019 at 15:15:06 UTC time zone, a backup will be repeated every day, and all the data will be stored in S3 under the ``my-backups`` bucket.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups' -s '2019-12-09T15:16:05Z' -i 24h
+ backup/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+Command returns the task ID (backup/3208ff15-6e8f-48b2-875c-d3c73f545410, in this case).
+This ID can be used to query the status of the backup task, to defer the task to another time, or to cancel the task See :ref:`Managing Tasks <sctool-managing-tasks>`.
+
+Schedule a daily, weekly, and monthly backup
+............................................
+This command series will schedule a backup on 9th Dec 2019 at 15:15:06 UTC time zone and will repeat the backup every day (keeping the last 7 days), every week (keeping the previous week), and every month (keeping the previous month).
+All the data will be stored in S3 under the ``my-backups`` bucket.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 7 -s '2019-12-09T15:16:05Z' -i 24h
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 2 -s '2019-12-09T15:16:05Z' -i 7d
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 1 -s '2019-12-09T15:16:05Z' -i 30d
+
+Schedule a backup for a specific DC, keyspace, or table
+--------------------------------------------------------
+In order to schedule a backup of a particular datacenter, you have to specify ``-dc`` parameter.
+You can specify more than one DC, or use a glob pattern to match multiple DCs or exclude some of them.
+
+For example, you have the following DCs in your cluster: dc1, dc2, dc3
+
+Backup one specific DC
+......................
+
+In this example you backup the only dc1 every 2 days.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster --dc 'dc1' -L 's3:dc1-backups' -i 2d
+
+
+Backup all DCs except for those specified
+.........................................
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d --dc '*,!dc2' -L 's3:my-backups'
+
+Backup to a specific location per DC
+....................................
+
+If your data centers are located in different regions, you can also specify different locations.
+If your buckets are created in the same regions as your data centers, you may save some bandwidth costs.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d --dc 'eu-dc,us-dc' -L 's3:eu-dc:eu-backups,s3:us-dc:us-backups'
+
+Backup a specific keyspace or table
+...................................
+
+In order to schedule a backup of a particular keyspace or table, you have to provide ``-K`` parameter.
+You can specify more than one keyspace/table or use a glob pattern to match multiple keyspaces/tables or exclude them.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d -K 'auth_service.*,!auth_service.lru_cache' --dc 'dc1' -L 's3:dc1-backups'
+
+Create an ad-hoc backup
+-----------------------
+
+An ad-hoc backup runs immediately and does not repeat.
+This procedure shows the most frequently used backup commands.
+Additional parameters can be used. Refer to :ref:`backup parameters <sctool-backup-parameters>`.
+
+**Procedure**
+
+To run an immediate backup on the prod-cluster cluster, saving the backup in my-backups, run the following command
+replacing the ``-c`` cluster flag with your cluster's cluster name or ID and replace the ``-L`` flag with your backup's location:
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups'
+
+Perform a dry run of a backup
+-----------------------------
+
+We recommend to use ``--dry-run`` parameter prior to scheduling a backup.
+It's a useful way to verify whether all necessary prerequisites are fulfilled.
+Add the parameter to the end of your backup command, so if it works, you can erase it and schedule the backup with no need to make any other changes.
+
+Dry run verifies if nodes are able to access the backup location provided.
+If it's not accessible, an error message will be displayed, and the backup is not be scheduled.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:test-bucket' --dry-run
+ NOTICE: dry run mode, backup is not scheduled
+
+ Error: failed to get backup target: location is not accessible
+ 192.168.100.23: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+ 192.168.100.22: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+ 192.168.100.21: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+
+The dry run gives you the chance to resolve all configuration or access issues before executing an actual backup.
+
+If the dry run completes successfully, a summary of the backup is displayed. For example:
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:backups' --dry-run
+ NOTICE: dry run mode, backup is not scheduled
+
+ Data Centers:
+ - dc1
+ - dc2
+ Keyspaces:
+ - system_auth all (2 tables)
+ - system_distributed all (1 table)
+ - system_traces all (5 tables)
+ - auth_service all (3 tables)
+
+ Disk size: ~10.4GB
+
+ Locations:
+ - s3:backups
+ Bandwidth Limits:
+ - Unlimited
+ Snapshot Parallel Limits:
+ - All hosts in parallel
+ Upload Parallel Limits:
+ - All hosts in parallel
+
+ Retention: Last 3 backups
+
+List the contents of a specific backup
+=======================================
+
+List all backups in s3
+----------------------
+
+Lists all backups currently in storage that are managed by Scylla Manager.
+
+.. code-block:: none
+
+ sctool backup list -c prod-cluster
+ Snapshots:
+ - sm_20191210145143UTC
+ - sm_20191210145027UTC
+ - sm_20191210144833UTC
+ Keyspaces:
+ - system_auth (2 tables)
+ - system_distributed (1 table)
+ - system_traces (5 tables)
+ - auth_service (3 tables)
+
+List files that were uploaded during a specific backup
+-------------------------------------------------------
+
+You can list all files that were uploaded during a particular backup.
+
+To list the files use:
+
+.. code-block:: none
+
+ sctool backup files -c prod-cluster --snapshot-tag sm_20191210145027UTC
+
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-CompressionInfo.db auth_service/roles
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-Data.db auth_service/roles
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-Digest.crc32 auth_service/roles
+ [...]
+
+Additional resources
+--------------------
+
+:doc:`Scylla Snapshots </kb/snapshots>`
+
+Delete backup snapshot
+=========================
+
+If you decide that you don't want to wait until a particular snapshot expires according to its retention policy, there is a command which allows you to delete a single snapshot from a provided location.
+
+This operation is aware of the Manager deduplication policy and will not delete any SSTable file referenced by another snapshot.
+
+.. warning:: This operation is irreversible! Use it with great caution!
+
+.. code-block:: none
+
+ sctool backup delete -c prod-cluster -L s3:backups --snapshot-tag sm_20191210145027UTC
+
+Once a snapshot is deleted, it won't show up in the backup listing anymore.
diff --git a/docs/operating-scylla/manager/2.1/configuration-file.rst b/docs/operating-scylla/manager/2.1/configuration-file.rst
--- a/docs/operating-scylla/manager/2.1/configuration-file.rst
+++ b/docs/operating-scylla/manager/2.1/configuration-file.rst
@@ -0,0 +1,179 @@
+==================
+Configuration file
+==================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+Scylla Manager has a single configuration file ``/etc/scylla-manager/scylla-manager.yaml``.
+Note that the file will open as read-only unless you edit it as the root user or by using sudo.
+Usually, there is no need to edit the configuration file.
+
+HTTP/HTTPS server settings
+==========================
+
+With server settings, you may specify if Scylla Manager should be available over HTTP, HTTPS, or both.
+
+.. code-block:: yaml
+
+ # Bind REST API to the specified TCP address using HTTP protocol.
+ # http: 127.0.0.1:56080
+
+ # Bind REST API to the specified TCP address using HTTPS protocol.
+ https: 127.0.0.1:56443
+
+Prometheus settings
+===================
+
+.. code-block:: yaml
+
+ # Bind prometheus API to the specified TCP address using HTTP protocol.
+ # By default it binds to all network interfaces, but you can restrict it
+ # by specifying it like this 127:0.0.1:56090 or any other combination
+ # of ip and port.
+ prometheus: ':56090'
+
+If changing prometheus IP or port, please remember to adjust rules in :doc:`prometheus server </operating-scylla/monitoring/2.2/monitoring-stack>`.
+
+.. code-block:: yaml
+
+ - targets:
+ - IP:56090
+
+Debug endpoint settings
+=======================
+
+In this section, you can specify the pprof debug server address.
+It allows you to run profiling on demand on a live application.
+By default, the server is running on port ``56112``.
+
+.. code-block:: none
+
+ debug: 127.0.0.1:56112
+
+.. _manager-2.1-logging-settings:
+
+Logging settings
+================
+
+Logging settings specify log output and level.
+
+.. code-block:: yaml
+
+ # Logging configuration.
+ logger:
+ # Where to output logs, syslog or stderr.
+ mode: syslog
+ # Available log levels are error, info, and debug.
+ level: info
+
+Database settings
+=================
+
+Database settings allow for `using a remote cluster <../use-a-remote-db>`_ to store Scylla Manager data.
+
+.. code-block:: yaml
+
+ # Scylla Manager database, used to store management data.
+ database:
+ hosts:
+ - 127.0.0.1
+ # Enable or disable client/server encryption.
+ # ssl: false
+ #
+ # Database credentials.
+ # user: user
+ # password: password
+ #
+ # Local datacenter name, specify if using a remote, multi-dc cluster.
+ # local_dc:
+ #
+ # Database connection timeout.
+ # timeout: 600ms
+ #
+ # Keyspace for management data, for create statement see /etc/scylla-manager/create_keyspace.cql.tpl.
+ # keyspace: scylla_manager
+ # replication_factor: 1
+
+ # Optional custom client/server encryption options.
+ #ssl:
+ # CA certificate used to validate server cert. If not set, will use he host's root CA set.
+ # cert_file:
+ #
+ # Verify the hostname and server cert.
+ # validate: true
+ #
+ # Client certificate and key in PEM format. It has to be provided when
+ # client_encryption_options.require_client_auth=true is set on server.
+ # user_cert_file:
+ # user_key_file
+
+Health check settings
+=====================
+
+Health check settings let you specify the timeout threshold.
+If there is no response from a node after this time period is reached, the :ref:`status <sctool_status>` report (``sctool status``) shows the node as ``DOWN``.
+
+.. code-block:: yaml
+
+ # Healthcheck service configuration.
+ #healthcheck:
+ # Timeout for CQL status checks.
+ # timeout: 250ms
+ # ssl_timeout: 750ms
+
+Backup settings
+===============
+
+Backup settings let you specify backup parameters.
+
+.. code-block:: yaml
+
+ # Backup service configuration.
+ #backup:
+ # Minimal amount of free disk space required to take a snapshot.
+ # disk_space_free_min_percent: 10
+ #
+ # Maximal time for a backup run to be considered fresh and can be continued from
+ # the same snapshot. If exceeded, a new run with a new snapshot will be created.
+ # Zero means no limit.
+ # age_max: 12h
+
+Repair settings
+===============
+
+Repair settings let you specify repair parameters.
+
+.. code-block:: yaml
+
+ # Repair service configuration.
+ #repair:
+ # Number of segments repaired by Scylla in a single repair command. Increase
+ # this value to make repairs faster, note that this may result in increased load
+ # on the cluster.
+ # segments_per_repair: 1
+ #
+ # Maximal number of shards on a host repaired at the same time. By default all
+ # shards are repaired in parallel.
+ # shard_parallel_max: 0
+ #
+ # Maximal allowed number of failed segments per shard. In case of a failure
+ # to repair a segment Scylla Manager will try to repair it multiple times
+ # depending on the specified number of retries (default 3). If the
+ # shard_failed_segments_max limit is exceeded repair task will immediately
+ # fail, and the next repair run will start the repair procedure from the beginning.
+ # shard_failed_segments_max: 25
+ #
+ # In case of an error, hold back repair for the specified amount of time.
+ # error_backoff: 5m
+ #
+ # Frequency Scylla Manager poll Scylla node for repair command status.
+ # poll_interval: 200ms
+ #
+ # Maximal time a paused repair is considered fresh and can be continued,
+ # if an exceeded repair will start from the beginning. Zero means no limit.
+ # age_max: 0
+ #
+ # Distribution of data among cores (shards) within a node.
+ # Copy value from Scylla configuration file.
+ # murmur3_partitioner_ignore_msb_bits: 12
diff --git a/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst b/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
--- a/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
+++ b/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
@@ -0,0 +1,40 @@
+==============================
+Extract schema from the backup
+==============================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. versionadded:: 2.1 Scylla Manager
+
+The first step to restoring a Scylla Manager backup is to restore the CQL schema from a text file.
+Scylla Manager version 2.1 creates a backup up of matching schema along with the snapshot.
+If you created the backup with Scylla Manager version 2.0 or you didn't provide credentials for a schema backup in Scylla Manager version 2.1, follow the instructions in `how to restore your schema from system table <../../2.0/extract-schema-from-system-table/>`_.
+
+If not, follow these steps to restore the schema from the Scylla Manager backup that has the schema stored along with the snapshot:
+
+**Procedure**
+
+#. List available backups:
+
+ .. code-block:: none
+
+ sctool backup list --cluster my-cluster --location s3:backup-bucket
+
+#. List files located in snapshot you want to restore. The first line contains a path to the schema so pipe it to ``aws s3 cp`` for download it to the current directory. For example:
+
+ .. code-block:: none
+
+ sctool backup files --cluster my-cluster -L s3:backup-bucket -T sm_20200513104924UTC --with-version | head -n 1 | xargs -n2 aws s3 cp
+ download: s3://backup-bucket/backup/schema/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz to ./task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz
+
+
+#. Create a directory to store the schema files and extract the archive containing the schema.
+
+ .. code-block:: none
+
+ mkdir ./schema
+ tar -xf task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz -C ./schema
+ ls ./schema
+ system_auth.cql system_distributed.cql system_schema.cql system_traces.cql user_data.cql
+
+Listed files are schema files for each keyspace in the backup. You can use each cql file to restore needed keyspace and continue the :ref:`restore procedure <restore-backup-restore-schema>`
diff --git a/docs/operating-scylla/manager/2.1/health-check.rst b/docs/operating-scylla/manager/2.1/health-check.rst
--- a/docs/operating-scylla/manager/2.1/health-check.rst
+++ b/docs/operating-scylla/manager/2.1/health-check.rst
@@ -0,0 +1,85 @@
+====================
+Cluster Health Check
+====================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager automatically adds a health check task to all new nodes when the cluster is added to the Scylla Manager and to all existing nodes
+during the upgrade procedure. You can see the tasks created by the healthcheck when you run
+the :ref:`sctool task list <sctool-task-list>` command.
+
+For example:
+
+.. code-block:: none
+
+ sctool task list -c manager-testcluster
+
+returns:
+
+.. code-block:: none
+
+ Cluster: manager-testcluster
+ ╭──────────────────────────────────────────────────────┬───────────────────────────────┬──────┬───────────┬────────╮
+ │ task │ next run │ ret. │ arguments │ status │
+ ├──────────────────────────────────────────────────────┼───────────────────────────────┼──────┼───────────┼────────┤
+ │ healthcheck/018da854-b9ff-4e0a-bae7-ca65c677c559 │ 02 Apr 19 18:06:31 UTC (+15s) │ 0 │ │ NEW │
+ │ healthcheck_api/597f237f-103d-4994-8167-3ff591150b7e │ 02 Apr 19 18:07:01 UTC (+1h) │ 0 │ │ NEW │
+ │ repair/21006f88-0c8c-4e11-9e84-83c319f80d0c │ 03 Apr 19 00:00:00 UTC (+7d) │ 3/3 │ │ NEW │
+ ╰──────────────────────────────────────────────────────┴───────────────────────────────┴──────┴───────────┴────────╯
+
+The health check task ensures that CQL native port is accessible on all the nodes. For each node, in parallel,
+Scylla Manager opens a connection to a CQL port and asks for server options. If there is no response or the response takes longer than 250 milliseconds, the node is considered to be DOWN otherwise, the node is considered to be UP.
+The results are available using the :ref:`sctool status <sctool_status>` command.
+
+For example:
+
+.. code-block:: none
+
+ sctool status -c prod-cluster2
+
+returns:
+
+.. code-block:: none
+
+ Datacenter: dc1
+ ╭──────────┬─────┬──────────┬────────────────╮
+ │ CQL │ SSL │ REST │ Host │
+ ├──────────┼─────┼──────────┼────────────────┤
+ │ UP (2ms) │ OFF │ UP (1ms) │ 192.168.100.11 │
+ │ UP (1ms) │ OFF │ UP (0ms) │ 192.168.100.12 │
+ │ UP (2ms) │ OFF │ UP (0ms) │ 192.168.100.13 │
+ ╰──────────┴─────┴──────────┴────────────────╯
+ Datacenter: dc2
+ ╭──────────┬─────┬──────────┬────────────────╮
+ │ CQL │ SSL │ REST │ Host │
+ ├──────────┼─────┼──────────┼────────────────┤
+ │ UP (2ms) │ OFF │ UP (1ms) │ 192.168.100.21 │
+ │ UP (1ms) │ OFF │ UP (1ms) │ 192.168.100.22 │
+ │ UP (1ms) │ OFF │ UP (1ms) │ 192.168.100.23 │
+ ╰──────────┴─────┴──────────┴────────────────╯
+
+If you have enabled the Scylla Monitoring stack, the Scylla Manager dashboard includes the same cluster status report.
+In addition, the Prometheus Alert Manager has an alert to report when a Scylla node health check fails.
+
+Scylla Manager just works!
+It reads CQL IP address and port from node configuration and can automatically detect TLS/SSL connection.
+There are two types of CQL health check `Credentials agnostic health check`_ and `CQL query health check`_.
+
+.. _manager-2.1-credentials-agnostic-health-check:
+
+Credentials agnostic health check
+---------------------------------
+
+Scylla Manager does not require database credentials to work.
+CQL health check is based on sending `CQL OPTIONS frame <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec#L302>`_ and does not start a CQL session.
+This is simple and effective but does not test CQL all the way down.
+For that, you may consider upgrading to `CQL query health check`_.
+
+.. _manager-2.1-cql-query-health-check:
+
+CQL query health check
+----------------------
+
+You may specify CQL ``username`` and ``password`` flags when adding a cluster to Scylla Manager using :ref:`sctool cluster add command <sctool-cluster-add>`.
+It's also possible to add or change that using :ref:`sctool cluster update command <sctool-cluster-update>`.
+Once Scylla Manager has CQL credential to the cluster, when performing a health check, it would try to connect to each node and execute ``SELECT now() FROM system.local`` query.
diff --git a/docs/operating-scylla/manager/2.1/index.rst b/docs/operating-scylla/manager/2.1/index.rst
--- a/docs/operating-scylla/manager/2.1/index.rst
+++ b/docs/operating-scylla/manager/2.1/index.rst
@@ -0,0 +1,46 @@
+:orphan:
+Scylla Manager 2.1
+==================
+.. toctree::
+ :hidden:
+
+ architecture
+ Install Scylla Manager <install>
+ Install Scylla Manager Agent <install-agent>
+ add-a-cluster
+ repair
+ backup
+ extract-schema-from-backup
+ restore-a-backup
+ health-check
+ sctool
+ monitoring-manager-integration
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+ use-a-remote-db
+ configuration-file
+ agent-configuration-file
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. panel-box::
+ :title: Scylla Manager
+ :id: "getting-started"
+ :class: my-panel
+
+ .. include:: /operating-scylla/manager/2.1/_common/manager-description.rst
+
+ * :doc:`Architecture <architecture>`
+ * :doc:`Install Scylla Manager <install>`
+ * :doc:`Install Scylla Manager Agent <install-agent>`
+ * :doc:`Add a cluster or a node to Scylla Manager <add-a-cluster>`
+ * :doc:`Repair <repair>`
+ * :doc:`Backup <backup>`
+ * :doc:`Extract schema from the backup <extract-schema-from-backup>`
+ * :doc:`Restore a backup <restore-a-backup>`
+ * :doc:`Health Check <health-check>`
+ * :doc:`sctool CLI Reference <sctool>`
+ * :doc:`Integration with Scylla Monitoring Stack <monitoring-manager-integration>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Use a remote database for Scylla Manager <use-a-remote-db>`
+ * :doc:`Configuration file <configuration-file>`
+ * :doc:`Scylla Manager Agent Configuration file <agent-configuration-file>`
diff --git a/docs/operating-scylla/manager/2.1/install-agent.rst b/docs/operating-scylla/manager/2.1/install-agent.rst
--- a/docs/operating-scylla/manager/2.1/install-agent.rst
+++ b/docs/operating-scylla/manager/2.1/install-agent.rst
@@ -0,0 +1,181 @@
+=================================
+Scylla Manager Agent Installation
+=================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager Agent is an executable, installed on each Scylla node.
+The Server communicates with the Agent over REST/HTTPS.
+The Agent communicates with the local Scylla node over the REST/HTTP.
+
+
+
+Install Scylla Manager Agent
+----------------------------
+
+Prerequisites
+=============
+
+* Scylla cluster running on any :doc:`OS supported by Scylla Manager 2.0 </getting-started/os-support>`
+* Traffic on port 10001 unblocked to Scylla nodes from the dedicated host
+
+.. note:: Scylla Manager only works with Scylla clusters that are using the Murmur3 partitioner (Scylla default partitioner). To check your cluster's partitioner, run the cqlsh command ``DESCRIBE CLUSTER``.
+
+Download packages
+=================
+
+**Procedure**
+
+Download and install Scylla Manager Agent (from the Scylla Manager Download Page) according to the desired version:
+
+* `Scylla Manager for Open Source <https://www.scylladb.com/download/open-source/scylla-manager/>`_ - Registration Required
+* Scylla Enterprise - Login to the `Customer Portal <https://www.scylladb.com/customer-portal/>`_
+
+Configure Scylla Manager Agent
+------------------------------
+There are three steps you need to complete:
+
+#. `Generate an authentication token`_
+#. Place the token parameters from `Configure authentication token parameters`_ in the Agent configuration file
+#. `Start Scylla Manager Agent service`_ or restart if already running. Confirm the service starts / restarts and runs without errors
+
+
+.. _manager-2.1-generate-auth-token:
+
+Generate an authentication token
+================================
+
+**Procedure**
+
+#. Generate an authentication token to be used to authenticate Scylla Manager with Scylla nodes.
+ This procedure is done **once** for each cluster. It is recommended to use a different token for each cluster.
+
+ .. note:: Use the same token on all nodes in the same cluster.
+
+ From **one node only** Run the token generator script.
+
+ For example:
+
+ .. code-block:: none
+
+ $ scyllamgr_auth_token_gen
+ 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+ If you want to change the token, you will need to repeat this procedure and place the new token on all nodes.
+ This procedure sets up the Scylla agent on each node.
+ Repeat the procedure for **every** Scylla node in the cluster that you want to be managed under Scylla Manager.
+
+
+Run `scyllamgr_agent_setup` script
+==================================
+
+**Procedure**
+
+#. Run the setup script to setup environment for the agent:
+
+ .. note:: Script requires sudo rights
+
+ .. code-block:: none
+
+ $ sudo scyllamgr_agent_setup
+ Do you want to create scylla-helper.slice if it does not exist?
+ Yes - limit Scylla Manager Agent and other helper programs memory. No - skip this step.
+ [YES/no] YES
+ Do you want the Scylla Manager Agent service to automatically start when the node boots?
+ Yes - automatically start Scylla Manager Agent when the node boots. No - skip this step.
+ [YES/no] YES
+
+ The first step relates to limited resources that are available to the agent, and second instructs systemd to run agent on node restart.
+
+.. _manager-2.1-configure-auth-token:
+
+Configure authentication token parameters
+=========================================
+
+**Procedure**
+
+#. Take the authentication token you generated from `Generate an authentication token`_, and place it into ``/etc/scylla-manager-agent/scylla-manager-agent.yaml`` as part of the ``auth_token`` :ref:`section <manger-2.1-agent-configuration-file-auth-token>`.
+
+ For Example:
+
+ .. code-block:: none
+
+ $ cat /etc/scylla-manager-agent/scylla-manager-agent.yaml
+ # Scylla Manager Agent config YAML
+
+ # Specify authentication token, the auth_token needs to be the same for all the
+ # nodes in a cluster. Use scyllamgr_auth_token_gen to generate the auth_token
+ # value.
+ auth_token: 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+
+Start Scylla Manager Agent service
+==================================
+
+**Procedure**
+
+#. Start Scylla Manager Agent service
+
+ .. code-block:: none
+
+ $ sudo systemctl start scylla-manager-agent
+
+#. Validate Scylla Manager Agent is running
+
+ .. code-block:: none
+
+ $ sudo systemctl status scylla-manager-agent
+ ● scylla-manager-agent.service - Scylla Manager Agent
+ Loaded: loaded (/usr/lib/systemd/system/scylla-manager-agent.service; disabled; vendor preset: disabled)
+ Active: active (running) since Wed 2019-10-30 10:46:51 UTC; 7s ago
+ Main PID: 14670 (scylla-manager-)
+ CGroup: /system.slice/scylla-manager-agent.service
+ └─14670 /usr/bin/scylla-manager-agent
+
+#. Enable the Scylla Manager Agent to run when the node starts.
+
+ .. code-block:: none
+
+ $ sudo systemctl enable scylla-manager-agent
+
+
+#. Repeat the procedure for **every** Scylla node in the cluster that you want to be managed under Scylla Manager, starting with `Configure authentication token parameters`_.
+
+.. _manager-2.1-prepare-nodes-for-backup:
+
+Prepare nodes for backup
+------------------------
+
+Adding the cluster to Scylla Manager automatically creates a backup task. Validate the connection to your backup location is accessible from Scylla Manager before adding the cluster to avoid errors.
+
+**Procedure**
+
+#. Create a storage location for the backup.
+ Currently, Scylla Manager 2.1 supports `S3 buckets <https://aws.amazon.com/s3/>`_ created on AWS.
+ You can use an S3 bucket that you already created.
+#. Choose how you want to configure access to the S3 Bucket.
+ You can use an IAM role (recommended), or you can add your AWS credentials to the agent configuration file.
+ This method is less secure as you will be propagating each node with this security information, and in cases where you need to change the key, you will have to replace it on each node.
+
+ * To use an IAM Role:
+
+ #. Create an `IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html>`_ for the S3 bucket which adheres to your company security policy. You can use the role you already created.
+ #. `Attach the IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html#attach-iam-role>`_ to **each EC2 instance (node)** in the cluster.
+
+ * To add your AWS credentials the Scylla Manager Agent configuration file:
+
+ #. Edit the ``/etc/scylla-manager-agent/scylla-manager-agent.yaml`` in the ``S3`` section your authentication information about the S3 bucket.
+ Refer to :ref:`AWS Credentials Configuration <manager-2.1-aws-credentials>` for details.
+
+#. Validate that the manager has access to the backup location.
+ If there is no response, the S3 bucket is accessible. If not, you will see an error.
+
+ .. code-block:: none
+
+ $ scylla-manager-agent check-location --location s3:<your S3 bucket name>
+
+
+Register a cluster
+------------------
+
+Continue with `Add a Cluster <../add-a-cluster>`_.
diff --git a/docs/operating-scylla/manager/2.1/install.rst b/docs/operating-scylla/manager/2.1/install.rst
--- a/docs/operating-scylla/manager/2.1/install.rst
+++ b/docs/operating-scylla/manager/2.1/install.rst
@@ -0,0 +1,132 @@
+===========================
+Scylla Manager Installation
+===========================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+System requirements
+===================
+
+Scylla Manager Server has modest systems requirements.
+While a minimal server can run on a system with 2 cores and 1GB RAM, the following configuration is recommended:
+
+* **CPU** - 2vCPUs
+* **Memory** - 8GB+ DRAM
+
+.. note:: If you are running :doc:`Scylla Monitoring Stack </operating-scylla/monitoring/2.2/monitoring-stack>` on the same server as Scylla Manager, your system should also meet the minimal :doc:`Monitoring requirements </operating-scylla/monitoring/2.2/monitoring-stack>`.
+
+Installation workflow
+=====================
+
+#. `Install Scylla Manager`_
+#. `Run the scyllamgr_setup script`_
+#. `Enable Bash Script Completion`_
+#. `Start Scylla Manager Service`_ and verify Scylla Manager is Running and that sctool is running
+
+
+Install Scylla Manager
+----------------------
+
+Choose one of the following installation methods:
+
+**Scylla Manager for Scylla Enterprise**
+
+#. Download and install Scylla Manager from the `Enterprise Download page <https://www.scylladb.com/download/enterprise/#manager>`_.
+#. Follow the entire installation procedure.
+#. Continue with `Run the scyllamgr_setup script`_.
+
+**Scylla Manager for Scylla Open Source**
+
+#. On the same node as you are installing Scylla Manager, download and install Scylla as a local database from the `Scylla Open Source Download page <https://www.scylladb.com/download/open-source/>`_.
+ There is no need to run the Scylla setup as it is taken care of by the ``scyllamgr_setup`` script.
+#. Download and Install Scylla Manager from the `Scylla Manager Open Source Download page <https://www.scylladb.com/download/open-source/scylla-manager/>`_.
+#. Follow the entire installation procedure.
+#. Continue with `Run the scyllamgr_setup script`_.
+
+.. _install-run-the-scylla-manager-setup-script:
+
+Run the scyllamgr_setup script
+------------------------------
+
+The Scylla Manager setup script automates the configuration of Scylla Manager by asking you some simple questions.
+It can be run in non-interactive mode if you'd like to script it.
+
+There are three decisions you need to make:
+
+* Do you want to enable the service to start automatically? If not, you will have to start the service manually each time you want to use it.
+* Do you want to set up and enable a local Scylla backend? If not, you will need to set up a `remote DB <../use-a-remote-db>`_
+* Do you want Scylla Manager to check periodically if updates are available? If not, you will need to check yourself.
+
+.. code-block:: none
+
+ scyllamgr_setup -h
+ Usage: scyllamgr_setup [-y][--no-scylla-setup][--no-enable-service][--no-check-for-updates]
+
+ Options:
+ -y, --assume-yes assume that the answer to any question which would be asked is yes
+ --no-scylla-setup skip setting up and enabling local Scylla instance as a storage backend for Scylla Manager
+ --no-enable-service skip enabling service
+ --no-check-for-updates skip enabling periodic check for updates
+ -h, --help print this help
+
+ Interactive mode is enabled when no flags are provided.
+
+**Procedure**
+
+#. Run the ``scyllamgr_setup`` script to configure the service. You can run the script in interactive mode (no flags) or automate your decision making by using flags.
+
+Enable bash script completion
+-----------------------------
+
+Enable bash completion for sctool: the Scylla Manager CLI. Alternatively, you can just open a new terminal.
+
+.. code-block:: none
+
+ source /etc/bash_completion.d/sctool.bash
+
+Start Scylla Manager service
+============================
+
+Scylla Manager integrates with ``systemd`` and can be started and stopped using ``systemctl`` command.
+
+**Procedure**
+
+#. Start the Scylla Manager server service.
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-manager.service
+
+#. Verify the Scylla Manager server service is running.
+
+ .. code-block:: none
+
+ sudo systemctl status scylla-manager.service
+ ● scylla-manager.service - Scylla Manager Server
+ Loaded: loaded (/usr/lib/systemd/system/scylla-manager.service; enabled; vendor preset: disabled)
+ Active: active (running) since Wed 2019-10-30 11:00:01 UTC; 20s ago
+ Main PID: 5805 (scylla-manager)
+ CGroup: /system.slice/scylla-manager.service
+ └─5805 /usr/bin/scylla-manager
+
+ ...
+
+ Hint: Some lines were ellipsized, use -l to show in full.
+
+
+#. Confirm sctool is running by displaying the sctool version.
+
+ .. code-block:: none
+
+ sctool version
+ Client version: 2.1-0.20200401.ce91f2ad
+ Server version: 2.1-0.20200401.ce91f2ad
+
+
+.. note:: The first time you run this command, Scylla Manager may take a few seconds to start because it must create the database schema.
+
+Install Scylla Manager Agent
+============================
+
+Continue with `Setup Scylla Manager Agent <../install-agent>`_
diff --git a/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst b/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
--- a/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
+++ b/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
@@ -0,0 +1,11 @@
+========================================
+Integration with Scylla Monitoring Stack
+========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+When used with Scylla Manager, the metrics for all of your managed clusters and alerts can be viewed using Scylla Monitoring.
+The Monitoring stack 2.1 Manager dashboard displays progress for all tasks, including: repairs, backups, node status, Scylla Manager status, and other metrics and Alerts.
+For more information, refer to the :doc:`Scylla Monitoring </operating-scylla/monitoring/index>` documentation.
+
+.. todo-add screenshot
diff --git a/docs/operating-scylla/manager/2.1/repair.rst b/docs/operating-scylla/manager/2.1/repair.rst
--- a/docs/operating-scylla/manager/2.1/repair.rst
+++ b/docs/operating-scylla/manager/2.1/repair.rst
@@ -0,0 +1,186 @@
+======
+Repair
+======
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. note:: If, after upgrading to the latest Scylla, you experience repairs that are slower than usual please consider :doc:`upgrading Scylla Manager to the appropriate version </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+When you create a cluster, a repair job is automatically scheduled.
+This task is set to occur each week by default, but you can change it to another time or add additional repair tasks.
+It is important to make sure that data across the nodes is consistent when maintaining your clusters.
+
+
+Why repair with Scylla Manager
+-------------------------------
+
+Scylla Manager automates the repair process and allows you to manage how and when the repair occurs.
+The advantage of repairing the cluster with Scylla Manager is:
+
+* Clusters are repaired node by node, ensuring that each database shard performs exactly one repair task at a time.
+ This gives the best repair parallelism on a node, shortens the overall repair time, and does not introduce unnecessary load.
+
+* If there is an error, Scylla Manager’s retry mechanism will try to run the repair again up to the number of retries that you set.
+
+* It has a restart (pause) mechanism that allows for restarting a repair from where it left off.
+
+* Repair what you want, when you want, and how often you want. Manager gives you that flexibility.
+
+* The most apparent advantage is that with Manager you do not have to manually SSH into every node as you do with nodetool.
+
+What can you repair with Scylla Manager
+----------------------------------------
+
+Scylla Manager can repair any item which it manages, specifically:
+
+* Specific tables, keyspaces, clusters, or data centers.
+
+* A group of tables, keyspaces, clusters or data centers.
+
+* All tables, keyspaces, clusters, or data centers.
+
+
+What sort of repairs can I run with Scylla Manager
+---------------------------------------------------
+
+You can run two types of repairs:
+
+* Ad-hoc - this is a one time repair
+
+* Scheduled - this repair is scheduled in advance and can repeat
+
+.. _manager-2.1-schedule-a-repair:
+
+Schedule a Repair
+-----------------
+
+By default, a cluster successfully added to Scylla Manager has a repair task created for it, which repairs the entire cluster.
+This is a repeating task that runs every week.
+You can change this repair, add additional repairs, or delete this repair.
+You can schedule repairs to run in the future on a regular basis, schedule repairs to run once, or schedule repairs to run immediately on an as-needed basis.
+Any repair can be rescheduled, paused, resumed, or deleted.
+For information on what is repaired and the types of repairs available, see `What can you repair with Scylla Manager`_.
+
+Create a scheduled repair
+.........................
+
+While the most recommended way to run a repair is across an entire cluster, repairs can be scheduled to run on a single/multiple datacenters, keyspaces, or tables.
+Scheduled repairs run every X days, depending on the frequency you set.
+The procedure here shows the most frequently used repair command.
+Additional parameters are located in the :ref:`sctool Reference <sctool-repair-parameters>`.
+
+**Procedure**
+
+Run the following sctoool repair command, replacing the parameters with your own parameters:
+
+* ``-c`` - cluster name - replace `prod-cluster` with the name of your cluster
+
+* ``-s`` - start-time - replace 2018-01-02T15:04:05-07:00 with the time you want the repair to begin
+
+* ``-i`` - interval - replace -i 7d with your own time interval
+
+For example:
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -s 2018-01-02T15:04:05-07:00 -i 7d
+
+2. The command returns the task ID. You will need this ID for additional actions.
+
+3. If you want to run the repair only once, remove the `-i` argument.
+
+4. If you want to run this command immediately, but still want the repair to repeat, keep the interval argument (``-i``), but remove the start-date (``-s``).
+
+Schedule an ad-hoc repair
+.........................
+
+An ad-hoc repair runs immediately and does not repeat.
+This procedure shows the most frequently used repair command.
+Additional parameters can be used. Refer to the :ref:`sctool Reference <sctool-repair-parameters>`.
+
+**Procedure**
+
+1. Run the following command, replacing the -c argument with your cluster name:
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster
+
+2. The command returns the task ID. You will need this ID for additional actions.
+
+Repair faster or slower
+.......................
+
+When scheduling repair, you may specify ``--intensity`` flag, the intensity meaning is:
+
+* For values > 1 intensity specifies the number of segments repaired by Scylla in a single repair command. Higher values result in higher speed and may increase cluster load.
+* For values < 1 intensity specifies what percent of node's shards repaired in parallel.
+* For intensity equal to 1 it will repair one segment in each repair command on all shards in parallel.
+* For zero intensity it uses limits specified in Scylla Manager `configuration <../configuration-file#repair-settings>`_.
+
+ Please note that this only works with versions that are **not** :doc:`row-level-repair enabled </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+**Example**
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --intensity 16
+
+.. _manager-2.1-reschedule-a-repair:
+
+Reschedule a Repair
+-------------------
+
+You can change the run time of a scheduled repair using the update repair command.
+The new time you set replaces the time which was previously set.
+This command requires the task ID, which was generated when you set the repair.
+This can be retrieved using the command sctool :ref:`task list <sctool-task-list>`.
+
+This example updates a task to run in 3 hours instead of whatever time it was supposed to run.
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd -s now+3h
+
+To start a scheduled repair immediately, run the following command inserting the task id and cluster name:
+
+.. code-block:: none
+
+ sctool task start repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+
+Pause a Repair
+--------------
+
+Pauses a specified task, provided it is running.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``. To start the task again, see `Resume a Repair`_.
+
+.. code-block:: none
+
+ sctool task stop repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+Resume a Repair
+---------------
+
+Restart a repair that is currently in the paused state.
+To start running a repair which is scheduled, but is currently not running, use the task update command.
+See `Reschedule a Repair`_.
+You will need the task ID for this action. This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task start repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+Delete a Repair
+---------------
+
+This action removes the repair from the task list.
+Once removed, you cannot resume the repair.
+You will have to create a new one.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task delete repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
diff --git a/docs/operating-scylla/manager/2.1/restore-a-backup.rst b/docs/operating-scylla/manager/2.1/restore-a-backup.rst
--- a/docs/operating-scylla/manager/2.1/restore-a-backup.rst
+++ b/docs/operating-scylla/manager/2.1/restore-a-backup.rst
@@ -0,0 +1,348 @@
+================
+Restore a Backup
+================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+This document provides information on how to restore data from backups that were taken using the Scylla Manager.
+
+There are two restore scenarios:
+
+#. Backup to the same topology cluster.
+ For example, restore data to the same source cluster.
+#. Backup to a different topology cluster.
+ For example, restore data to a smaller or bigger cluster, a cluster with a different rack or DC topology, or different token distribution.
+
+**Workflow**
+
+#. `Prepare for restore`_
+#. `Upload data to Scylla`_
+
+Prepare for restore
+===================
+
+No matter which backup scenario you are using, the procedures in this workflow apply.
+
+**Workflow**
+
+#. `Make sure Scylla cluster is up`_
+#. `Install Scylla Manager`_
+#. `Register the cluster with the Scylla Manager`_
+#. `Identify relevant snapshot`_
+#. `Restore the schema`_
+
+Make sure Scylla cluster is up
+------------------------------
+
+Make sure that your Scylla cluster is up and that there are no issues with networking, disk space, or memory.
+If you need help, you can check official documentation on :doc:`operational procedures for cluster management </operating-scylla/procedures/cluster-management/index>`.
+
+Install Scylla Manager
+----------------------
+
+You need a working Scylla Manager setup to list backups. If you don't have it installed, please follow official instructions on `how to install Scylla Manager <../install/>`_ first.
+
+Nodes must have access to the locations of the backups as per instructions in the official documentation for :ref:`installing Scylla Manager Agent <manager-2.1-prepare-nodes-for-backup>`.
+
+Register the cluster with the Scylla Manager
+--------------------------------------------
+
+This section only applies to situations where a registered cluster that was originally used for the backup is missing from the Scylla Manager.
+In that case, a new cluster must be registered before you can access the backups created with the old one.
+This example demonstrates adding a cluster named "cluster1" with initial node IP 18.185.31.99, instructs Scylla Manager not to schedule a default repair, and forcing uuid of the new cluster to ebec29cd-e768-4b66-aac3-8e8943bcaa76:
+
+ .. code-block:: none
+
+ sctool cluster add --host 18.185.31.99 --name cluster1 --without-repair -id ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ __
+ / \ Cluster added! You can set it as default, by exporting its name or ID as env variable:
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ | | $ export SCYLLA_MANAGER_CLUSTER=cluster1
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c cluster1
+ \___/ $ sctool task list -c cluster1
+
+Cluster is created, and we can proceed to list old backups.
+If the uuid of the old cluster is lost, there is a workaround with ``--all-clusters`` parameter.
+In that case, just register the cluster and proceed to the next step.
+
+Identify relevant snapshot
+--------------------------
+
+**Procedure**
+
+#. List all available backups and choose the one you would like to restore.
+ Run: :ref:`sctool backup list <sctool-backup-list>`, to lists all backups for the cluster.
+ This command will list backups only created with provided cluster (``-c clust1``).
+ If you don't have uuid of the old cluster, you can use ``--all-clusters`` to list all backups from all clusters that are available in the target location:
+
+ .. code-block:: none
+
+ sctool backup list -c cluster1 --all-clusters -L s3:backup-bucket
+ Cluster: 7313fda0-6ebd-4513-8af0-67ac8e30077b
+
+ Snapshots:
+ - sm_20200513131519UTC (563.07GiB)
+ - sm_20200513080459UTC (563.07GiB)
+ - sm_20200513072744UTC (563.07GiB)
+ - sm_20200513071719UTC (563.07GiB)
+ - sm_20200513070907UTC (563.07GiB)
+ - sm_20200513065522UTC (563.07GiB)
+ - sm_20200513063046UTC (563.16GiB)
+ - sm_20200513060818UTC (534.00GiB)
+ Keyspaces:
+ - system_auth (4 tables)
+ - system_distributed (2 tables)
+ - system_schema (12 tables)
+ - system_traces (5 tables)
+ - user_data (100 tables)
+
+ Here, for example, we have eight different snapshots to choose from.
+ Snapshot tags encode the date they were taken in UTC time zone.
+ For example, ``sm_20200513131519UTC`` was taken on 13/05/2020 at 13:15 and 19 seconds UTC.
+ The data source for the listing is the cluster backup locations.
+ Listing may take some time, depending on how big the cluster is and how many backups there are.
+
+.. _restore-backup-restore-schema:
+
+Restore the schema
+------------------
+
+Scylla Manager 2.1 can store schema with your backup.
+To extract schema files for each keyspace from the backup, please refer to the official documentation for `extracting schema from the backup <../../2.1/extract-schema-from-backup>`_. For convenience, here is the continuation of our example with the list of steps for restoring schema:
+
+#. Download schema from the backup store to the current dir. It's in the first line of the ``backup_files.out`` output:
+
+ .. code-block:: none
+
+ sctool backup files --cluster my-cluster -L s3:backup-bucket -T sm_20200513104924UTC --with-version | head -n 1 | xargs -n2 aws s3 cp
+ download: s3://backup-bucket/backup/schema/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz to ./task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz
+
+#. Extract schema files by decompressing archive:
+
+ .. code-block:: none
+
+ mkdir ./schema
+ tar -xf task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz -C ./schema
+ ls ./schema
+ system_auth.cql system_distributed.cql system_schema.cql system_traces.cql user_data.cql
+
+
+* If you do *not* have the schema file available, you can `extract the schema from system table <https://manager.docs.scylladb.com/branch-2.2/restore/extract-schema-from-metadata.html>`_.
+
+Full schema restore procedure can be found at :ref:`steps 1 to 5 <restore-procedure>`.
+For convenience, here is the list of steps for our example (WARNING: these can be destructive operations):
+
+#. Run the ``nodetool drain`` command to ensure the data is flushed to the SSTables.
+
+#. Shut down the node:
+
+ .. code-block:: none
+
+ sudo systemctl stop scylla-server
+
+#. Delete all files in the commitlog:
+
+ .. code-block:: none
+
+ sudo rm -rf /var/lib/scylla/commitlog/*
+
+#. Delete all the files in the user_data.data_* tables (only files, not directories):
+
+ .. code-block:: none
+
+ sudo rm -f /var/lib/scylla/data/user_data/data_0-6e856600017f11e790f4000000000000/*
+
+If cluster is added with CQL credentials (see :doc:`Add Cluster <add-a-cluster>` for reference) Scylla Manager would backup schema in CQL format.
+To obtain CQL schema from a particular backup, use ``sctool backup files`` command, for example:
+
+.. code-block:: none
+
+ sctool backup files -c my-cluster -L s3:backups -T sm_20191210145143UTC
+
+The first output line is a path to schemas archive, for example:
+
+.. code-block:: none
+
+ s3://backups/backup/schema/cluster/ed63b474-2c05-4f4f-b084-94541dd86e7a/task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz ./
+
+This archive contains a single CQL file for each keyspace in the backup.
+
+.. code-block:: none
+
+ tar -ztvf task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz
+ -rw------- 0/0 2366 2020-05-08 14:38 system_auth.cql
+ -rw------- 0/0 931 2020-05-08 14:38 system_distributed.cql
+ -rw------- 0/0 11557 2020-05-08 14:38 system_schema.cql
+ -rw------- 0/0 4483 2020-05-08 14:38 system_traces.cql
+
+To restore the schema, you need to execute the files with cqlsh command.
+
+**Procedure**
+
+#. Download schema archive
+
+ .. code-block:: none
+
+ aws s3 cp s3://backups/backup/schema/cluster/ed63b474-2c05-4f4f-b084-94541dd86e7a/task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz ./
+
+#. Extract CQL files from archive
+
+ .. code-block:: none
+
+ tar -xzvf task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz
+
+#. Copy CQL files for desired keyspaces to a cluster node
+#. On node execute CQL files using cqlsh
+
+ .. code-block:: none
+
+ cqlsh -f my_keyspace.cql
+
+Upload data to Scylla
+=====================
+
+You can either upload the data:
+
+* `To the same cluster`_: with the same nodes, topology, and the same token distribution **OR**
+* `To a new cluster`_: of any number of nodes
+
+
+To the same cluster
+-------------------
+
+List the backup files
+.....................
+
+List the backup files needed on each node and save the list to a file.
+
+If you are listing old backups from the new cluster use ``--all-clusters`` parameter.
+
+.. code-block:: none
+
+ sctool backup files -c cluster1 --snapshot-tag sm_20200513131519UTC \
+ --with-version \
+ --location s3:backup-bucket \
+ > backup_files.out
+
+Snapshot information is now stored in ``backup_files.out`` file.
+Each line of the ``backup_files.out`` file contains mapping between the path to the SSTable file in the backup bucket, and it's mapping to keyspace/table.
+If Scylla Manager is configured to store database schemas with the backups, then the first line in the file listing is the path to the schema archive.
+
+For example:
+
+.. code-block:: none
+
+ s3://backup-bucket/backup/sst/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/dc/AWS_EU_CENTRAL_1/node/92de78b1-6c77-4788-b513-2fff5a178fe5/keyspace/user_data/table/data_65/a2667040944811eaaf9d000000000000/la-72-big-Index.db user_data/data_65-a2667040944811eaaf9d000000000000
+
+Path contains metadata, for example:
+
+* Cluster ID - 7313fda0-6ebd-4513-8af0-67ac8e30077b
+* Data Center - AWS_EU_CENTRAL_1
+* Directory - /var/lib/scylla/data/user_data/data_65-a2667040944811eaaf9d000000000000/
+* Keyspace - user_data
+
+.. code-block:: none
+
+ sctool backup files -c prod-cluster --snapshot-tag sm_20191210145027UTC \
+ --with-version > backup_files.out
+
+Each line describes a backed-up file and where it should be downloaded. For example
+
+.. code-block:: none
+
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-CompressionInfo.db auth_service/roles-5bc52802de2535edaeab188eecebb090
+
+This file has to be copied to:
+
+* Cluster - 1d781354-9f9f-47cc-ad45-f8f890569656
+* Data Center - dc1
+* Node - ece658c2-e587-49a5-9fea-7b0992e19607
+* Directory - /var/lib/scylla/data/auth_service/roles-5bc52802de2535edaeab188eecebb090/upload
+
+Download the backup files
+.........................
+
+This step must be executed on **each node** in the cluster.
+
+#. Copy ``backup_files.out`` file as ``/tmp/backup_files.out`` on the node.
+
+#. Run ``nodetool status`` to get to know the node ID.
+
+#. Download data into table directories.
+ As the file is kept in S3 so we can use S3 CLI to download it (this step may be different with other storage providers).
+ Grep can be used to filter specific files to restore.
+ With node UUID we can filter files only for a single node.
+ With a keyspace name, we can filter files only for a single keyspace.
+
+ .. code-block:: none
+
+ cd /var/lib/scylla/data
+
+ # Filter only files for a single node.
+ grep ece658c2-e587-49a5-9fea-7b0992e19607 /tmp/backup_files.out | xargs -n2 aws s3 cp
+
+#. Make sure that all files are owned by the Scylla user and group.
+ We must ensure that permissions are right after copy:
+
+ .. code-block:: none
+
+ sudo chown -R scylla:scylla /var/lib/scylla/data/user_data/
+
+#. Start the Scylla nodes:
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-server
+
+Repair
+......
+
+After performing the above on all nodes, repair the cluster with Scylla Manager Repair.
+This makes sure that the data is consistent on all nodes and between each node.
+
+To a new cluster
+----------------
+
+In order to restore a backup to a cluster that has a different topology, you have to use an external tool called :doc:`sstableloader </operating-scylla/procedures/cassandra-to-scylla-migration-process>`.
+This procedure is much slower than restoring to the same topology cluster.
+
+**Procedure**
+
+#. Start up the nodes if they are not running after schema restore:
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-server
+
+#. List all the backup files and save the list to a file.
+
+ Use ``--all-clusters`` if you are restoring from the cluster that no longer exists.
+
+ .. code-block:: none
+
+ sctool backup files -c cluster1 --snapshot-tag sm_20200513131519UTC --location s3:backup-bucket > backup_files.out
+
+#. Copy ``backup_files.out`` file as ``/tmp/backup_files.out`` on the host where ``sstableloader`` is installed.
+
+#. Download all files created during backup into temporary location:
+
+ .. code-block:: none
+
+ mkdir snapshot
+ cd snapshot
+ # Create temporary directory structure.
+ cat /tmp/backup_files.out | awk '{print $2}' | xargs mkdir -p
+ # Download snapshot files.
+ cat /tmp/backup_files.out | xargs -n2 aws s3 cp
+
+#. Execute the following command for each table by providing a list of node IP addresses and path to sstable files on node that has sstableloader installed:
+
+ .. code-block:: none
+
+ # Loads table user_data.data_0 into four node cluster.
+ sstableloader -d '35.158.14.221,18.157.98.72,3.122.196.197,3.126.2.205' ./user_data/data_0 --username scylla --password <password>
+
+After tables are restored, verify the validity of your data by running queries on your database.
diff --git a/docs/operating-scylla/manager/2.1/sctool.rst b/docs/operating-scylla/manager/2.1/sctool.rst
--- a/docs/operating-scylla/manager/2.1/sctool.rst
+++ b/docs/operating-scylla/manager/2.1/sctool.rst
@@ -0,0 +1,1607 @@
+=====================
+Sctool CLI Reference
+=====================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+This document is a complete reference for the sctool CLI.
+The commands are in alphabetical order.
+
+
+About sctool
+------------
+
+``sctool`` is a Command Line Interface (CLI) for the Scylla Manager server.
+The server communicates with managed Scylla clusters and performs cluster-wide operations such as automatic repair and backup.
+
+**Usage**
+
+.. code-block:: none
+
+ sctool command [flags] [global flags]
+
+Global flags
+============
+
+* ``--api-cert-file <path>`` - specifies the path to HTTPS client certificate used to access the Scylla Manager server
+* ``--api-key-file <path>`` - specifies the path to HTTPS client key used to access the Scylla Manager server
+* ``--api-url URL`` - URL of Scylla Manager server (default "http://localhost:8889/api/v1")
+* ``-c, --cluster <cluster_name>`` - Specifies the target cluster name or ID
+* ``-h, --help`` - Displays help for commands. Use ``sctool [command] --help`` for help about a specific command.
+
+Environment variables
+=====================
+
+sctool uses the following environment variables:
+
+* `SCYLLA_MANAGER_CLUSTER` - if set, specifies the default value for the ``-c, --cluster`` flag, in commands that support it.
+* `SCYLLA_MANAGER_API_URL` - if set, specifies the default value for the ``--api-url`` flag; it can be useful when using sctool with a remote Scylla Manager server.
+
+The environment variables may be saved in your ``~/.bashrc`` file so that the variables are set after login.
+
+Backup clusters
+---------------
+
+The backup commands allow you to: create a backup (ad-hoc or scheduled), list the contents of a backup, and list the backups of a cluster.
+A Scylla cluster must be added (`cluster add`_) before management tasks can be initiated.
+
+.. code-block:: none
+
+ sctool backup <command> [global flags] [parameters]
+
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `backup`_
+ - Schedule a backup (ad-hoc or scheduled).
+ * - `backup files`_
+ - List contents of a given backup.
+ * - `backup list`_
+ - List backups of a given cluster.
+ * - `backup delete`_
+ - Deletes one of available snapshots.
+
+.. _sctool-backup:
+
+backup
+======
+
+The backup command allows you to schedule or run ad-hoc cluster backup.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup --cluster <id|name> --location <list of locations> [--dc <list>]
+ [--dry-run] [--force] [--interval <time-unit>]
+ [--keyspace <list of glob patterns to find keyspaces>]
+ [--num-retries <times to rerun a failed task>]
+ [--rate-limit <list of rate limits>] [--retention <number of backups to store>]
+ [--show-tables]
+ [--snapshot-parallel <list of parallelism limits>] [--start-date <date>]
+ [--upload-parallel <list of parallelism limits>] [global flags]
+
+.. _sctool-backup-parameters:
+
+backup parameters
+.................
+
+In addition to the `Global flags`_, backup takes the following parameters:
+
+
+=====
+
+``--dc <list of glob patterns>``
+
+A comma-separated list of datacenter glob patterns, e.g. 'dc1,!otherdc*' used to specify the DCs to include or exclude from backup, separated by a comma.
+This can also include glob patterns.
+
+.. include:: _common/glob.rst
+
+=====
+
+``--dry-run``
+
+Validates and prints backup information without actually scheduling a backup.
+
+=====
+
+``--force``
+
+Forces backup to skip database validation and schedules a backup even if there are no matching keyspaces/tables.
+
+=====
+
+``-i, --interval <time-unit>``
+
+Scheduled Intervals for backups to repeat every X time, where X can be:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+
+For example: ``-i 3d2h10m``
+
+**Default: 0** - this means the task does not recur.
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma used to include or exclude keyspaces from the backup.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[dc:]<provider>:<name>`` ex. ``s3:my-bucket``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` at the moment is ``s3``.
+
+=====
+
+``-r, --num-retries <times to rerun a failed task>``
+
+The number of times a scheduled task will retry to run before failing.
+
+**Default: 3**
+
+=====
+
+``--rate-limit <list of rate limits>``
+
+Limits the upload rate (as expressed in megabytes (MB) per second), which a snapshot file can be uploaded from a Scylla node to its backup destination.
+For example, an S3 bucket.
+You can set limits for more than one DC using a comma-separated list expressed in the format ``[<dc>:]<limit>``.
+The <dc>: part is optional and is only needed when different datacenters require different upload limits.
+
+**Default: 100**
+
+=====
+
+``--retention <number of backups to store>``
+
+The number of backups to store.
+Once this number is reached, the next backup which comes in from this destination will initiate a purge of the oldest backup.
+
+**Default: 3**
+
+=====
+
+``--show-tables``
+
+Prints table names together with keyspace.
+
+=====
+
+``--snapshot-parallel <list of parallelism limits>``
+
+A comma-separated list of snapshot parallelism limits in the format ``[<dc>:]<limit>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and allows for specifying different limits in selected datacenters.
+If The <dc>: part is not set, the limit is global (e.g. 'dc1:2,5'). The runs are parallel in ``n`` nodes (2 in dc1 (as shown in the example) and ``n`` nodes in all the other datacenters.
+
+=====
+
+``-s, --start-date <date>``
+
+Specifies the task start date expressed in the RFC3339 format or ``now[+duration]``, e.g. ``now+3d2h10m``, valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+**Default: now**
+
+=====
+
+``--upload-parallel <list of parallelism limits>``
+
+A comma-separated list of upload parallelism limits in the format ``[<dc>:]<limit>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and allows for specifying different limits in selected datacenters.
+If The <dc>: part is not set, the limit is global (e.g. 'dc1:2,5'). The runs are parallel in ``n`` nodes (2 in dc1 (as shown in the example) and ``n`` nodes in all the other datacenters.
+
+=====
+
+Example: backup
+................
+
+This example backs up the entire cluster named prod-cluster.
+The backup begins on December 9, 2019 at 16:05 and will repeat at this time every 24 hours.
+The backup is stored in s3 in a directory named ``my-backups``.
+Additional examples are available in `Backup Scylla Clusters <../backup/>`_
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -s '2019-12-09T15:16:05Z' -i 24h -L 's3:my-backups'
+ backup/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+.. _sctool-backup-list:
+
+backup list
+===========
+
+These commands allow you to list backups of a given cluster.
+
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup list [--all clusters] [--keyspace <list of glob patterns to find keyspaces>] [--location <list of backup locations>]
+ [--max-date <date>] [--min-date <date>] [--show-tables][global flags]
+
+backup list parameters
+......................
+
+In addition to the `Global flags`_, backup list takes the following parameters:
+
+=====
+
+``--all-clusters``
+
+Shows backups for all clusters
+
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``--max-date <date>``
+
+Specifies maximal snapshot date expressed in RFC3339 form or ``now[+duration]``.
+For example: ``now+3d2h10m`` Valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+=====
+
+``--min-date <date>``
+
+Specifies minimal snapshot date expressed in RFC3339 form or ``now[+duration]``.
+For example: ``now+3d2h10m`` Valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+=====
+
+``--show-tables``
+
+Prints table names together with keyspace.
+
+=====
+
+Example: backup list
+....................
+
+
+.. code-block:: none
+
+ sctool backup list -c prod-cluster --show-tables
+ Snapshots:
+ - sm_20191210145143UTC
+ - sm_20191210145027UTC
+ - sm_20191210144833UTC
+ Keyspaces:
+ - system_auth (role_members, roles)
+ - system_distributed (view_build_status)
+ - system_traces (events, node_slow_log, node_slow_log_time_idx, sessions, sessions_time_idx)
+ - test_keyspace_dc1_rf2 (void1)
+ - test_keyspace_dc1_rf3 (void1)
+ - test_keyspace_dc2_rf2 (void1)
+ - test_keyspace_dc2_rf3 (void1)
+ - test_keyspace_rf2 (void1)
+ - test_keyspace_rf3 (void1)
+
+backup files
+============
+
+This command allows you to list the content of a given backup.
+This command lists files that were uploaded during the backup procedure.
+It outputs the remote paths of files together with keyspace/table information separated by a delimiter that you provide.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup files [--all clusters] [--keyspace <list of glob patterns to find keyspaces>]
+ [--location <list of backup locations>] [global flags]
+
+backup files parameters
+.......................
+
+In addition to the `Global flags`_, backup files add takes the following parameters:
+
+=====
+
+``--all-clusters``
+
+Shows backups for all clusters
+
+=====
+
+``-d, --delimiter <delimiter-character>``
+
+Dictates which character will be used as whitespace between remote file path and information about keyspace and table.
+
+**Default: '\t'**
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``-T, --snapshot-tag <tag>``
+
+Snapshot tag as read from the backup listing
+
+=====
+
+Example: backup files
+.....................
+
+.. code-block:: none
+
+ sctool backup files --keyspace system_auth
+
+The command output has the following format:
+
+.. code-block:: none
+
+ <provider>://<bucket-name>/backup/sst/cluster/<cluster-id>/dc/<dc-id>/
+ node/<node-id>/keyspace/<keyspace-name>/table/<table-name>/<table-uuid>/
+ <filename><delimiter><keyspace-name>/<table-name>
+
+Example:
+
+.. code-block:: none
+
+ s3://backups/backup/sst/cluster/7d8f190f-c98d-4a06-8bb5-ae96633ee69a/dc/dc2/
+ node/f3c6386b-6d54-4546-a2e8-627fff62d3af/keyspace/system_sec/table/roles/5bc52802de2535edaeab188eecebb090/
+ mc-2-big-TOC.txt system_sec/table
+
+From this information we know the following:
+
+* Provider - s3
+* Bucket name - backups
+* Cluster ID - 7d8f190f-c98d-4a06-8bb5-ae96633ee69a
+* DC - DC2
+* Node - f3c6386b-6d54-4546-a2e8-627fff62d3af
+* Keyspace - system_sec
+* Table name - roles
+* Table UUID - 5bc52802de2535edaeab188eecebb090
+* File name - mc-2-big-TOC.txt
+* Delimiter - whitespace character (ie ' ')
+* Keyspace / table name - system_sec/table
+
+See `Restore <restore>`_ on information how to use these files to restore a backup.
+
+backup delete
+=============
+
+This command allows you to delete files that were uploaded during the backup procedure.
+Deduplicated files are persisted unless their reference count drops to zero.
+
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup delete --snapshot-tag <snapshot tag> [--location <list of backup locations>] [global flags]
+
+backup delete parameters
+........................
+
+In addition to the `Global flags`_, backup delete takes the following parameters:
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to look for the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``-T, --snapshot-tag <tag>``
+
+Snapshot tag as read from the backup listing.
+
+=====
+
+Example: backup delete
+......................
+
+.. code-block:: none
+
+ sctool backup delete --snapshot-tag sm_20200526115228UTC
+
+The command does not output anything unless an error happens.
+
+Managing clusters
+-----------------
+
+The cluster commands allow you to add, delete, list, and update clusters.
+A Scylla cluster must be added (`cluster add`_) before management tasks can be initiated.
+
+.. code-block:: none
+
+ sctool cluster <command> [flags] [global flags]
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `cluster add`_
+ - Add a cluster to manager.
+ * - `cluster delete`_
+ - Delete a cluster from manager.
+ * - `cluster list`_
+ - Show managed clusters.
+ * - `cluster update`_
+ - Modify a cluster.
+
+.. _sctool-cluster-add:
+
+cluster add
+===========
+
+This command adds the specified cluster to the manager.
+Once a Scylla cluster is added, a weekly repair task is also added.
+
+Before continuing, make sure the cluster that you want to add is prepared for it,
+see `Add a cluster to Scylla Manager <../add-a-cluster>`_ for instructions.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster add --host <node IP> --auth-token <token>[--name <alias>][--without-repair][global flags]
+
+cluster add parameters
+......................
+
+In addition to the `Global flags`_, cluster add takes the following parameters:
+
+=====
+
+.. include:: _common/cluster-params.rst
+
+=====
+
+Example: cluster add
+....................
+
+This example is only the command that you use to add the cluster to Scylla Manager, not the entire procedure for adding a cluster.
+The procedure is detailed in `Add a cluster to Scylla Manager <../add-a-cluster>`_.
+
+.. code-block:: none
+
+ sctool cluster add --host 34.203.122.52 --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+ c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ __
+ / \ Cluster added! You can set it as default, by exporting env variable.
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ | | $ export SCYLLA_MANAGER_CLUSTER=prod-cluster
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c prod-cluster
+ \___/ $ sctool task list -c prod-cluster
+
+Example (IPv6):
+
+.. code-block:: none
+
+ sctool cluster add --host 2a05:d018:223:f00:971d:14af:6418:fe2d --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+cluster delete
+==============
+
+This command deletes the specified cluster from the manager.
+Note that there is no confirmation or warning to confirm.
+If you deleted the cluster by mistake, you will need to add it again.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster delete --cluster <id|name> [global flags]
+
+.. note:: If you are removing the cluster from Scylla Manager and you are using Scylla Monitoring, remove the target from Prometheus Target list in the prometheus/scylla_manager_servers.yml file.
+
+
+cluster delete parameters
+.........................
+
+In addition to `Global flags`_, cluster delete takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: cluster delete
+.......................
+
+.. code-block:: none
+
+ sctool cluster delete -c prod-cluster
+
+cluster list
+============
+
+Lists the managed clusters.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster list [global flags]
+
+cluster list parameters
+.......................
+
+cluster list takes the `Global flags`_.
+
+Example: cluster list
+.....................
+
+.. code-block:: none
+
+ sctool cluster list
+ ╭──────────────────────────────────────┬──────────────╮
+ │ ID │ Name │
+ ├──────────────────────────────────────┼──────────────┤
+ │ db7faf98-7cc4-4a08-b707-2bc59d65551e │ prod-cluster │
+ ╰──────────────────────────────────────┴──────────────╯
+
+.. _sctool-cluster-update:
+
+cluster update
+==============
+
+This command modifies managed cluster parameters.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster update --cluster <id|name> [--host <node IP>] [--auth-token <token>] [--name <alias>] [--without-repair] [global flags]
+
+
+cluster update parameters
+.........................
+
+In addition to the `Global flags`_, cluster update takes all the `cluster add parameters`_.
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+.. include:: _common/cluster-params.rst
+
+=====
+
+Example: cluster update
+.......................
+
+In this example, the cluster named ``cluster`` has been renamed to ``prod-cluster``.
+
+.. code-block:: none
+
+ sctool cluster update --prod-cluster cluster --name prod-cluster
+
+Scheduling repairs
+------------------
+
+repair
+======
+
+The repair commands allow you to schedule repairs for a specified cluster.
+
+.. code-block:: none
+
+ sctool repair --cluster <id|name> [--dc <list of glob patterns>] [--dry-run]
+ [--fail-fast] [--force] [--host <node IP>] [--interval <time between task runs>]
+ [--intensity <float>]
+ [--keyspace <list of glob patterns>] [--num-retries <times to rerun a failed task>]
+ [--start-date <now+duration|RFC3339>]
+ [--token-ranges <pr|npr|all>] [--with-hosts <list of node IPs>][global flags]
+
+.. _sctool-repair-parameters:
+
+repair parameters
+.................
+
+In addition to `Global flags`_, repair takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--dc <list of glob patterns>``
+
+List of data centers to be repaired, separated by a comma.
+This can also include glob patterns.
+
+.. include:: _common/glob.rst
+
+**Example**
+
+Given the following data centers: *us-east-1*, *us-east-2*, *us-west-1*, *us-west-2*.
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Parameter
+ - Selects
+ * - ``--dc us-east-1,us-west-2``
+ - *us-east-1*, *us-west-2*
+ * - ``--dc 'us-east-*'``
+ - *us-east-1*, *us-east-2*
+ * - ``--dc '*','!us-east-'``
+ - *us-west-1*, *us-west-2*
+
+**Default:** everything - all data centers
+
+=====
+
+``--dry-run``
+
+Validates and displays repair information without actually scheduling the repair.
+This allows you to display what will happen should the repair run with the parameters you set.
+
+**Example**
+
+Given the following keyspaces:
+
+* system_auth
+* system_distributed
+* system_traces
+* test_keyspace_dc1_rf2, test_keyspace_dc1_rf3, and test_keyspace_dc2_rf2
+* keyspace_dc2_rf3
+* test_keyspace_rf2 and test_keyspace_rf3
+
+The following command will run a repair on all keyspaces **except** for test_keyspace_dc1_rf2 in dry-run mode.
+
+
+.. code-block:: none
+
+ sctool repair --dry-run -K '*,!test_keyspace_dc1_rf2'
+ NOTICE: dry run mode, repair is not scheduled
+
+ Data Centers:
+ - dc1
+ - dc2
+ Keyspace: system_auth
+ (all tables)
+ Keyspace: system_distributed
+ (all tables)
+ Keyspace: system_traces
+ (all tables)
+ Keyspace: test_keyspace_dc1_rf3
+ (all tables)
+ Keyspace: test_keyspace_dc2_rf2
+ (all tables)
+ Keyspace: test_keyspace_dc2_rf3
+ (all tables)
+ Keyspace: test_keyspace_rf2
+ (all tables)
+ Keyspace: test_keyspace_rf3
+ (all tables)
+
+**Example with error**
+
+.. code-block:: none
+
+ sctool repair -K 'system*.bla' --dry-run -c bla
+ NOTICE: dry run mode, repair is not scheduled
+
+ Error: API error (status 400)
+ {
+ "message": "no matching units found for filters, ks=[system*.*bla*]",
+ "trace_id": "b_mSOUoOSyqSnDtk9EANyg"
+ }
+
+=====
+
+``--fail-fast``
+
+Stops the repair process on the first error.
+
+**Default:** False
+
+=====
+
+``--force``
+
+Forces the repair to skip database validation and schedules a repair even if there aren't any matching keyspaces/tables.
+This means that if the glob patterns match nothing, a repair will still run.
+
+Default: False
+
+=====
+
+``--host <node IP>``
+
+Host to repair, you may use that to repair given host with other hosts (--with-hosts), you may also want to specify token ranges to repair (--token-ranges).
+You can use either an IPv4 or IPv6 address.
+
+=====
+
+``--intensity <float>``
+
+Repair speed, higher values result in higher speed and may increase cluster load.
+Values in a range (0-1) result in lower speed and load.
+
+When intensity is below 1, the repair is executed only on the specified fraction of shards at the same time.
+Please note that this only works with versions that are not :doc:`row-level-repair enabled </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+**Default:** 0
+
+=====
+
+``-K, --keyspace <list of glob patterns>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+**Example**
+
+Given the following tables:
+
+* *shopping_cart.cart*
+* *orders.orders_by_date_2018_11_01*
+* *orders.orders_by_date_2018_11_15*
+* *orders.orders_by_date_2018_11_29*
+* *orders.orders_by_date_2018_12_06*
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Parameter
+ - Selects
+ * - ``-K '*'``
+ - *everything - all tables in all keyspaces*
+ * - ``-K shopping_cart``
+ - *shopping_cart.cart*
+ * - ``-K '*,!orders'``
+ - *shopping_cart.cart*
+ * - ``-K orders.'orders.2018_11_'``
+ - *orders.orders_by_date_2018_11_01*
+ *orders.orders_by_date_2018_11_15*
+ *orders.orders_by_date_2018_11_29*
+ * - ``-K 'orders.*2018_1?_2?'``
+ - *orders.orders_by_date_2018_11_29*
+ * - ``-K 'orders.*2018_11?[19]'``
+ - *orders.orders_by_date_2018_11_01*
+ *orders.orders_by_date_2018_11_29*
+
+**Default:** everything - all tables in all keyspaces
+
+=====
+
+``--token-ranges <pr|npr|all>``
+
+Dictates which token range is used for the repair.
+There are three to choose from:
+
+* ``pr``- restricts the repair to the Primary token Range. This is a token range where the node is the first replica in the ring. It is important that if you choose this option to make sure it runs on **every** node in the cluster in order to repair the entire ring.
+* ``npr``- runs the repair on the non-primary token range.
+* ``all``- repairs all ranges, primary and non-primary.
+
+**Default:** pr
+
+.. note:: ``--token-ranges`` requires ``--host`` or ``--with-hosts`` to also be used.
+
+=====
+
+``--with-hosts <list of node IPs>``
+
+List of hosts to repair with separated by a comma.
+When the repair runs the repair compares the ``--host`` with the ``--with-hosts``.
+
+Use **caution** with this flag.
+It disables the built-in Scylla mechanism for repair and uses only the IP or hostname you set here.
+If there is a situation where there is missing data in the --with-host cluster, it will be deleted from the subsequent clusters.
+You can use either an IPv4 or IPv6 address.
+
+=====
+
+.. include:: _common/task-params.rst
+
+=====
+
+Example: Schedule a repair
+..........................
+
+Repairs can be scheduled to run on selected keyspaces/tables, nodes, or datacenters.
+Scheduled repairs run every *n* days, depending on the frequency you set.
+A scheduled repair runs at the time you set it to run at.
+If no time is given, the repair runs immediately.
+Repairs can run once or can run at a set schedule based on a time interval.
+
+Repair cluster weekly
+^^^^^^^^^^^^^^^^^^^^^
+
+In this example, you create a repair task for a cluster named *prod-cluster*.
+The task begins on May 2, 2019 at 3:04 PM.
+It repeats every week at this time.
+As there are no datacenters or keyspaces listed, all datacenters and all data in the specified cluster are repaired.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -s 2019-05-02T15:04:05-07:00 --interval 7d
+
+The system replies with a repair task ID.
+You can use this ID to change the start time, stop the repair, or cancel the repair.
+
+.. code-block:: none
+
+ repair/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+Repair datacenters in a region weekly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example repairs all datacenters starting with the name *dc-asia-*, such as *dc-asia-1*.
+The repair begins on September 15, 2018 at 7:00 PM (JST, for example) and runs every week.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --dc 'asia-*' -s 2018-09-15T19:00:05-07:00 --interval 7d
+
+Repair selected keyspaces/tables weekly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using glob patterns gives you additional flexibility in selecting both keyspaces and tables.
+This example repairs all tables in the *orders* keyspace starting with *2018_11_* prefix.
+The repair is scheduled to run on December 4, 2018 at 8:00 AM and will run after that point every week.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -K 'orders.2018_12_' -s 2018-12-04T08:00:05-07:00 --interval 7d
+
+Repair a specific host once
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By listing the host IP address, you run a repair only on the specified host.
+The argument ``--token-ranges all`` specifies that the repair will run on all token ranges (primary and secondary).
+
+Example (IPv4):
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --host 198.100.51.11 --token-ranges all
+
+Monitoring clusters
+-------------------
+
+.. _sctool_status:
+
+status
+======
+
+The status command is an extended version of ``nodetool status``.
+It can show status for all the managed clusters.
+The first column shows node status in :doc:`nodetool format </operating-scylla/nodetool-commands/status>`.
+The CQL column shows the CQL status, SSL indicator if SSL is enabled on a node, and time the check took.
+
+Available statuses are:
+
+* UP - Situation normal
+* DOWN - Failed to connect to host or CQL error
+* UNAUTHORISED - Wrong username or password - only if ``username`` is specified for cluster
+* TIMEOUT - Timeout
+
+The REST column shows the status of Scylla Manager Server to Scylla API communication and the time the check took.
+
+Available statuses are:
+
+* UP - Situation normal
+* DOWN - Failed to connect to host
+* HTTP XXX - HTTP failure and its status code
+* UNAUTHORISED - Wrong ``api-key`` specified for cluster or in :ref:`Scylla Manager Agent configuration file <manger-2.1-agent-configuration-file-auth-token>`
+* TIMEOUT - Timeout
+
+The status information is also available as a metric in the Scylla Monitoring Manager dashboard.
+The `healthcheck` task checks nodes every 15 seconds. The interval can be changed using `task update`_ command.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool status [global flags]
+
+status parameters
+..................
+
+status takes the `Global flags`_.
+
+Example: status
+................
+
+.. code-block:: none
+
+ sctool status
+ Cluster: prod-cluster (c1bbabf3-cad1-4a59-ab8f-84e2a73b623f)
+ Datacenter: eu-west
+ ╭────┬───────────────┬────────────┬──────────────┬──────────────────────────────────────╮
+ │ │ CQL │ REST │ Host │ Host ID │
+ ├────┼───────────────┼────────────┼──────────────┼──────────────────────────────────────┤
+ │ UN │ UP SSL (42ms) │ UP (52ms) │ 10.0.114.68 │ 45a7390d-d162-4daa-8bff-6469c9956f8b │
+ │ UN │ UP SSL (38ms) │ UP (88ms) │ 10.0.138.46 │ 8dad7fc7-5a82-4fbb-8901-f6f60c12342a │
+ │ UN │ UP SSL (38ms) │ UP (298ms) │ 10.0.196.204 │ 44eebe5b-e0cb-4e45-961f-4ad175592977 │
+ │ UN │ UP SSL (43ms) │ UP (159ms) │ 10.0.66.115 │ 918a52aa-cc42-43a4-a499-f7b1ccb53b18 │
+ ╰────┴───────────────┴────────────┴──────────────┴──────────────────────────────────────╯
+
+.. _sctool-managing-tasks:
+
+Managing tasks
+--------------
+
+The task command set allows you to schedule, start, stop and modify tasks.
+
+.. code-block:: none
+
+ sctool task <command> [flags] [global flags]
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `task delete`_
+ - Delete a task.
+ * - `task history`_
+ - Show run history of a task.
+ * - `task list`_
+ - Show available tasks and their last run status.
+ * - `task progress`_
+ - Show the task progress.
+ * - `task start`_
+ - Start executing a task.
+ * - `task stop`_
+ - Stop executing a task.
+ * - `task update`_
+ - Modify a task.
+
+task delete
+===========
+
+This command deletes a task from the manager.
+Note that a task can be disabled if you want to temporarily turn it off (see `task update`_).
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task delete <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task delete parameters
+......................
+
+In addition to the `Global Flags`_, task delete takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: task delete
+....................
+
+This example deletes the repair from the task list.
+You need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+Once the repair is removed, you cannot resume the repair.
+You will have to create a new one.
+
+.. code-block:: none
+
+ sctool task delete -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+
+task history
+============
+
+This command shows details about task run history for a given task.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task history <task type/id> --cluster <id|name>
+ [--limit <number of results>] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task history parameters
+.......................
+
+In addition to the `Global Flags`_, task history takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--limit <number of results>``
+
+Limits the number of returned results.
+
+**Default** 10
+
+=====
+
+Example: task history
+.....................
+
+.. code-block:: none
+
+ sctool task history repair/730a134a-4792-4139-bc6c-75d2ba7a1e62 -c prod-cluster
+
+ ╭──────────────────────────────────────┬────────────────────────┬────────────────────────┬──────────┬────────────────────────────────────────────────╮
+ │ ID │ Start time │ End time │ Duration │ Status │
+ ├──────────────────────────────────────┼────────────────────────┼────────────────────────┼──────────┼────────────────────────────────────────────────┤
+ │ f81ba8ad-ad79-11e8-915f-42010af000a9 │ 01 Jan 18 00:00:00 UTC │ 01 Jan 18 00:00:30 UTC │ 30s │ STOPPED │
+ │ e02d2caf-ad2a-11e8-915e-42010af000a9 │ 31 Feb 18 14:33:05 UTC │ 31 Feb 18 14:34:35 UTC │ 90s │ SUCCESS │
+ │ 7a8c6fe2-ad29-11e8-915d-42010af000a9 │ 31 Mar 18 14:23:20 UTC │ 31 Mar 18 14:23:20 UTC │ 0s │ ERROR failed to load units … │
+ │ 08f75324-610d-11e9-9aac-42010af000a9 │ 05 Apr 19 12:33:42 UTC │ 05 Apr 19 12:33:43 UTC │ 1s │ DONE │
+ │ 000681e1-610d-11e9-9aab-42010af000a9 │ 09 Apr 19 12:33:27 UTC │ 09 Apr 19 12:33:28 UTC │ 1s │ DONE │
+ │ f715fb82-610c-11e9-9aaa-42010af000a9 │ 11 Apr 19 12:33:12 UTC │ 11 Apr 19 12:33:13 UTC │ 1s │ DONE │
+ │ ee251fc0-610c-11e9-9aa9-42010af000a9 │ 13 Apr 19 12:32:57 UTC │ 13 Apr 19 12:32:58 UTC │ 1s │ DONE │
+ │ e5343b52-610c-11e9-9aa8-42010af000a9 │ 15 Apr 19 15:32:42 UTC │ 15 Apr 19 15:32:43 UTC │ 1s │ DONE │
+ │ dc435562-610c-11e9-9aa7-42010af000a9 │ 17 Apr 19 12:32:27 UTC │ 17 Apr 19 12:32:28 UTC │ 1s │ DONE │
+ ╰──────────────────────────────────────┴────────────────────────┴────────────────────────┴──────────┴────────────────────────────────────────────────╯
+
+.. _sctool-task-list:
+
+task list
+=========
+
+This command shows all of the scheduled tasks for the specified cluster.
+If the cluster is not set, this will output a table for every cluster.
+Each row contains task type and ID, separated by a slash, task properties, next activation, and last status information.
+For more information on a task, consult `task history`_ and `task progress`_.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task list [--cluster <id|name>] [--all] [--sort <sort-key>]
+ [--status <status>] [--type <task type>] [global flags]
+
+task list parameters
+....................
+
+In addition to the `Global Flags`_, task list takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--all``
+
+Lists all tasks, including those which have been disabled.
+Disabled tasks are prefixed with ``*``.
+For example ``*repair/afe9a610-e4c7-4d05-860e-5a0ddf14d7aa``.
+
+=====
+
+``--sort <sort-key>``
+
+Returns a list of tasks sorted according to the last run status and sort key which you provide.
+Accepted sort key values are:
+
+* ``start-time``
+* ``next-activation``
+* ``end-time``
+* ``status``
+
+``start-time``, ``next-activation``, and ``end-time`` are sorted in ascending order.
+
+``status`` is sorted using the following order: "NEW", "RUNNING", "STOPPED", "DONE", "ERROR", "ABORTED".
+
+=====
+
+``--status <status>``
+
+Filters tasks according to their last run status.
+Accepted values are NEW, STARTING, RUNNING, STOPPING, STOPPED, DONE, ERROR, ABORTED.
+
+=====
+
+``-t, --type <task type>``
+
+Display only tasks of a given type.
+
+=====
+
+Example: task list
+..................
+
+.. code-block:: none
+
+ sctool task list
+ Cluster: prod-cluster (c1bbabf3-cad1-4a59-ab8f-84e2a73b623f)
+ ╭───────────────────────────────────────────────────────┬──────────────────────────────────────┬───────────────────────────────┬─────────╮
+ │ Task │ Arguments │ Next run │ Status │
+ ├───────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┼─────────┤
+ │ healthcheck/ebccaade-4487-4ce9-80ee-d39e295c752e │ │ 02 Apr 20 10:47:48 UTC (+15s) │ DONE │
+ │ healthcheck_rest/eff03af0-21ee-473a-b674-5e4bedc37b8b │ │ 02 Apr 20 11:02:03 UTC (+1h) │ DONE │
+ │ backup/2d7df8bb-69bc-4782-a52f-1ec87f9c2c1c │ -L s3:manager-backup-tests-eu-west-1 │ │ RUNNING │
+ ╰───────────────────────────────────────────────────────┴──────────────────────────────────────┴───────────────────────────────┴─────────╯
+
+Setting the ``--all`` flag will also list disabled tasks which are not shown in the regular view.
+Disabled tasks are prefixed with a ``*``.
+
+task progress
+=============
+
+This command shows details of the latest run (or still running) task.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task progress <task type/id> --cluster <id|name> [--details] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task progress parameters
+........................
+
+
+In addition to the `Global flags`_, repair progress takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--details``
+
+More detailed progress data, depending on task type.
+
+====
+
+Example: task progress
+......................
+
+This example displays the progress of a running repair.
+
+.. code-block:: none
+
+ sctool task progress repair/dff91fd1-f430-4f98-8932-373644fe647e -c prod-cluster
+ Status: RUNNING
+ Start time: 17 Apr 19 12:55:57 UTC
+ Duration: 46s
+ Progress: 0.45%
+ Datacenters:
+ - dc1
+ - dc2
+ ╭───────────────────────┬───────╮
+ │ system_auth │ 3.85% │
+ │ system_distributed │ 0.00% │
+ │ system_traces │ 0.00% │
+ │ test_keyspace_dc1_rf2 │ 0.00% │
+ │ test_keyspace_dc1_rf3 │ 0.00% │
+ │ test_keyspace_dc2_rf2 │ 0.00% │
+ │ test_keyspace_dc2_rf3 │ 0.00% │
+ │ test_keyspace_rf2 │ 0.00% │
+ │ test_keyspace_rf3 │ 0.00% │
+ ╰───────────────────────┴───────╯
+
+The ``--details`` flag shows each host’s shard repair progress, with the shards numbered from zero.
+
+.. code-block:: none
+
+ sctool task progress repair/dff91fd1-f430-4f98-8932-373644fe647e -c prod-cluster --details
+ Status: RUNNING
+ Start time: 17 Apr 19 12:55:57 UTC
+ Duration: 3m0s
+ Progress: 1.91%
+ Datacenters:
+ - dc1
+ - dc2
+ ╭───────────────────────┬────────╮
+ │ system_auth │ 16.30% │
+ │ system_distributed │ 0.00% │
+ │ system_traces │ 0.00% │
+ │ test_keyspace_dc1_rf2 │ 0.00% │
+ │ test_keyspace_dc1_rf3 │ 0.00% │
+ │ test_keyspace_dc2_rf2 │ 0.00% │
+ │ test_keyspace_dc2_rf3 │ 0.00% │
+ │ test_keyspace_rf2 │ 0.00% │
+ │ test_keyspace_rf3 │ 0.00% │
+ ╰───────────────────────┴────────╯
+ ╭───────────────────────┬───────┬──────────┬───────────────┬─────────────────┬───────────────╮
+ │ system_auth │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 100.00% │ 748 │ 748 │ 0 │
+ │ 192.168.100.11 │ 1 │ 100.00% │ 757 │ 757 │ 0 │
+ │ 192.168.100.22 │ 0 │ 2.40% │ 791 │ 19 │ 0 │
+ │ 192.168.100.22 │ 1 │ 2.35% │ 807 │ 19 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 752 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 747 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ system_distributed │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 748 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 757 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 791 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ system_traces │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 748 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 757 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 791 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 807 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 752 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 747 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc1_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc1_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc2_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc2_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ╰───────────────────────┴───────┴──────────┴───────────────┴─────────────────┴───────────────╯
+
+Example with a backup task
+
+.. code-block:: none
+
+ sctool task progress -c prod-cluster backup/f0642e3e-e1cb-44ba-8447-f8d43672bcfd
+ Arguments: -L s3:manager-backup-tests-eu-west-1
+ Status: RUNNING
+ Start time: 02 Apr 20 10:09:27 UTC
+ Duration: 40m30s
+ Progress: 1%
+ Snapshot Tag: sm_20200402100931UTC
+ Datacenters:
+ - eu-west
+ ╭──────────────┬──────────┬───────────┬──────────┬──────────────┬────────╮
+ │ Host │ Progress │ Size │ Success │ Deduplicated │ Failed │
+ ├──────────────┼──────────┼───────────┼──────────┼──────────────┼────────┤
+ │ 10.0.114.68 │ 1% │ 952.11GiB │ 13.22GiB │ 538KiB │ 0B │
+ │ 10.0.138.46 │ 1% │ 938.00GiB │ 13.43GiB │ 830MiB │ 0B │
+ │ 10.0.196.204 │ 1% │ 934.58GiB │ 13.79GiB │ 206MiB │ 0B │
+ │ 10.0.66.115 │ 1% │ 897.43GiB │ 12.17GiB │ 523KiB │ 0B │
+ ╰──────────────┴──────────┴───────────┴──────────┴──────────────┴────────╯
+
+task start
+==========
+
+This command initiates a task run.
+Note that if a repair task is already running on a cluster, other repair tasks runs on that cluster will fail.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task start <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task start parameters
+.....................
+
+In addition to the `Global Flags`_, task start takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--continue``
+
+Try to resume the last run.
+
+**Default** true
+
+=====
+
+Example: task start
+...................
+
+This example resumes running, which was previously stopped.
+To start a repair that is scheduled but is currently not running, use the ``task update`` command making sure to set the start time to ``now``.
+See `Example: task update`_.
+
+
+If you have stopped a repair, you can resume it by running the following command.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task start -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+task stop
+=========
+
+Stops a specified task, stopping an already stopped task has no effect.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task stop <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task stop parameters
+.....................
+
+In addition to the `Global flags`_, task stop takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: task stop
+..................
+
+This example immediately stops running repair.
+The task is not deleted and can be resumed at a later time.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task stop -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+task update
+===========
+
+This command changes generic task parameters, such as schedule.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task update <task type/id> --cluster <id|name> [--enabled <bool>]
+ [--name <alias>] [--tags <list of tags>]
+ [--interval <time between task runs>]
+ [--start-date <now+duration|RFC3339>]
+ [--num-retries <times to rerun a failed task>] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task update parameters
+......................
+
+In addition to `Global flags`_, task stop takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``-e, --enabled``
+
+Setting enabled to false disables the task.
+The disabled task is not executed and hidden from the task list.
+To show disabled tasks invoke ``sctool task list --all`` (see `task list`_).
+
+**Default** true
+
+=====
+
+``-n, --name <alias>``
+
+Adds a name to a task.
+
+=====
+
+``--tags <list of tags>``
+
+Allows you to tag the task with a list of text.
+
+=====
+
+.. include:: _common/task-params.rst
+
+=====
+
+Example: task update
+....................
+
+This example disables the task
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/4d79ee63-7721-4105-8c6a-5b98c65c3e21 --enabled false
+
+
+This example reschedules the repair to run in 3 hours from now instead of whatever time it was supposed to run and sets the repair to run every two days.
+The new time you set replaces the time which was previously set.
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd -s now+3h --interval 2d
+
+Show Scylla Manager version
+---------------------------
+
+This command shows the currently installed sctool version and the Scylla Manager server version.
+
+version
+=======
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool version [flags] [global flags]
+
+version parameters
+..................
+
+version takes the `Global flags`_.
+
+Example: version
+................
+
+.. code-block:: none
+
+ sctool version
+ Client version: 2.1-0.20200401.ce91f2ad
+ Server version: 2.1-0.20200401.ce91f2ad
+
diff --git a/docs/operating-scylla/manager/2.1/use-a-remote-db.rst b/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
--- a/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
+++ b/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
@@ -0,0 +1,123 @@
+========================================
+Use a remote database for Scylla Manager
+========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+When you install Scylla Manager, it installs a local instance of Scylla to use as it's a database.
+You are not required to use the local instance and can use Scylla Manager with a remote database.
+
+
+**Requirements**
+
+* Scylla cluster to be used as Scylla Manager data store.
+* Package ``scylla-manager`` installed.
+
+Remove local Scylla instance
+============================
+
+The ``scylla-manager`` package is a meta package that pulls both Scylla and Scylla Manager packages.
+If you do not intend to use the local Scylla instance, you may remove it.
+
+**Procedure**
+
+1. Remove ``scylla-enterprise`` package.
+
+.. code-block:: none
+
+ sudo yum remove scylla-enterprise -y
+
+2. Remove related packages. This would also remove the Scylla Manager.
+
+.. code-block:: none
+
+ sudo yum autoremove -y
+
+3. Install the Scylla Manager client and server packages.
+
+.. code-block:: none
+
+ sudo yum install scylla-manager-client scylla-manager-server -y
+
+Edit Scylla Manager configuration
+=================================
+
+Scylla Manager configuration file ``/etc/scylla-manager/scylla-manager.yaml`` contains a database configuration section.
+
+.. code-block:: yaml
+
+ # Scylla Manager database, used to store management data.
+ database:
+ hosts:
+ - 127.0.0.1
+ # Enable or disable client/server encryption.
+ # ssl: false
+ #
+ # Database credentials.
+ # user: user
+ # password: password
+ #
+ # Local datacenter name, specify if using a remote, multi-dc cluster.
+ # local_dc:
+ #
+ # Database connection timeout.
+ # timeout: 600ms
+ #
+ # Keyspace for management data, for create statement see /etc/scylla-manager/create_keyspace.cql.tpl.
+ # keyspace: scylla_manager
+ # replication_factor: 1
+
+
+Using an editor, open the file and change relevant parameters.
+
+**Procedure**
+
+1. Edit the ``hosts`` parameter, change the IP address to the IP address or addresses of the remote cluster.
+
+2. If client/server encryption is enabled, uncomment and set the ``ssl`` parameter to ``true``.
+ Additional SSL configuration options can be set in the ``ssl`` configuration section.
+
+ .. code-block:: yaml
+
+ # Optional custom client/server encryption options.
+ #ssl:
+ # CA certificate used to validate server cert. If not set will use he host's root CA set.
+ # cert_file:
+ #
+ # Verify the hostname and server cert.
+ # validate: true
+ #
+ # Client certificate and key in PEM format. It has to be provided when
+ # client_encryption_options.require_client_auth=true is set on server.
+ # user_cert_file:
+ # user_key_file
+
+3. If authentication is needed, uncomment and edit the ``user`` and ``password`` parameters.
+
+4. If the remote cluster contains more than one node:
+
+ * If it's a single DC deployment, uncomment and edit the ``replication_factor`` parameter to match the required replication factor.
+ Note that this would use a simple replication strategy (SimpleStrategy).
+ If you want to use a different replication strategy, create ``scylla_manager`` keyspace (or another matching the ``keyspace`` parameter) yourself.
+ Refer to :doc:`Scylla Architecture - Fault Tolerance </architecture/architecture-fault-tolerance>` for more information on replication.
+
+ * If it's a multi DC deployment, create ``scylla_manager`` keyspace (or other matching the ``keyspace`` parameter) yourself.
+ Uncomment and edit the ``local_dc`` parameter to specify the local datacenter.
+
+Sample configuration of Scylla Manager working with a remote cluster with authentication and replication factor 3 could look like this.
+
+.. code-block:: yaml
+
+ database:
+ hosts:
+ - 198.100.51.11
+ - 198.100.51.12
+ user: user
+ password: password
+ replication_factor: 3
+
+Setup Scylla Manager
+====================
+
+Continue with :ref:`setup script <install-run-the-scylla-manager-setup-script>`.
diff --git a/docs/operating-scylla/manager/_common/manager-description.rst b/docs/operating-scylla/manager/_common/manager-description.rst
--- a/docs/operating-scylla/manager/_common/manager-description.rst
+++ b/docs/operating-scylla/manager/_common/manager-description.rst
@@ -0,0 +1,4 @@
+Scylla Manager is a centralized cluster administration and recurrent tasks automation tool. Scylla Manager can schedule tasks such as repairs and backups.
+Scylla Manager is available for Scylla Enterprise customers and Scylla Open Source users. With Scylla Open Source, Scylla Manager is limited to 5 nodes.
+See the Scylla Manager Proprietary Software `License Agreement <https://www.scylladb.com/scylla-manager-software-license-agreement/>`_ for details.
+Scylla Manager runs with any version of Scylla Enterprise or Open source.
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/_common/manager-index.rst b/docs/operating-scylla/manager/_common/manager-index.rst
--- a/docs/operating-scylla/manager/_common/manager-index.rst
+++ b/docs/operating-scylla/manager/_common/manager-index.rst
@@ -0,0 +1,4 @@
+
+Older Scylla Manager releases:
+
+* :doc:`Scylla Manager 2.1 </operating-scylla/manager/2.1/index>`
diff --git a/docs/operating-scylla/manager/_common/note-versions.rst b/docs/operating-scylla/manager/_common/note-versions.rst
--- a/docs/operating-scylla/manager/_common/note-versions.rst
+++ b/docs/operating-scylla/manager/_common/note-versions.rst
@@ -0,0 +1,2 @@
+.. note:: You are not reading the most recent version of this documentation.
+ Go to the **latest** version of `Scylla Manager Documentation <http://scylladb.github.io/scylla-manager/>`_.
diff --git a/docs/operating-scylla/manager/index.rst b/docs/operating-scylla/manager/index.rst
--- a/docs/operating-scylla/manager/index.rst
+++ b/docs/operating-scylla/manager/index.rst
@@ -0,0 +1,27 @@
+Scylla Manager
+==============
+
+.. toctree::
+ :hidden:
+ :maxdepth: 2
+
+ Scylla Manager Docs <https://manager.docs.scylladb.com>
+ Upgrade Scylla Manager </upgrade/upgrade-manager/index>
+ Monitoring Support Matrix <https://monitoring.docs.scylladb.com/stable/reference/matrix.html>
+
+.. include:: /operating-scylla/manager/_common/manager-description.rst
+
+.. image:: scylla-...@2x.png
+ :width: 250
+ :alt: Scylla Manager Logo
+
+To get started, read the `Scylla Manager Documentation <https://manager.docs.scylladb.com/stable/index.html>`_ (Scylla Manager release 2.2 and later)
+
+Additional information:
+
+* :doc:`Upgrade Scylla Manager </upgrade/upgrade-manager/index>`
+* `Scylla Monitoring Support Matrix <https://monitoring.docs.scylladb.com/stable/reference/matrix.html>`_ - refer to this document before installing Manager if you plan to use Scylla Manager with Scylla Monitoring stack.
+* `Cluster Management, Repair and Scylla Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/>`_ on Scylla University, includes theory and some hands-on labs
+
+.. include:: /operating-scylla/manager/_common/manager-index.rst
+
diff --git a/docs/operating-scylla/manager/scylla-...@2x.png b/docs/operating-scylla/manager/scylla-...@2x.png
--- a/docs/operating-scylla/manager/scylla-...@2x.png
+++ b/docs/operating-scylla/manager/scylla-...@2x.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/1.png b/docs/operating-scylla/monitoring/2.2/1.png
--- a/docs/operating-scylla/monitoring/2.2/1.png
+++ b/docs/operating-scylla/monitoring/2.2/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/2.png b/docs/operating-scylla/monitoring/2.2/2.png
--- a/docs/operating-scylla/monitoring/2.2/2.png
+++ b/docs/operating-scylla/monitoring/2.2/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/3.png b/docs/operating-scylla/monitoring/2.2/3.png
--- a/docs/operating-scylla/monitoring/2.2/3.png
+++ b/docs/operating-scylla/monitoring/2.2/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/4.png b/docs/operating-scylla/monitoring/2.2/4.png
--- a/docs/operating-scylla/monitoring/2.2/4.png
+++ b/docs/operating-scylla/monitoring/2.2/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.2/alertmanager.png b/docs/operating-scylla/monitoring/2.2/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.2/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.2/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/grafana.png b/docs/operating-scylla/monitoring/2.2/grafana.png
--- a/docs/operating-scylla/monitoring/2.2/grafana.png
+++ b/docs/operating-scylla/monitoring/2.2/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/index.rst b/docs/operating-scylla/monitoring/2.2/index.rst
--- a/docs/operating-scylla/monitoring/2.2/index.rst
+++ b/docs/operating-scylla/monitoring/2.2/index.rst
@@ -0,0 +1,36 @@
+:orphan:
+Scylla Monitoring 2.2
+=====================
+
+.. toctree::
+ :hidden:
+ :maxdepth: 1
+
+ Scylla Monitoring Stack <monitoring-stack>
+ Scylla Monitoring Interfaces <monitoring-apis>
+ Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>
+ Troubleshoot Monitoring <monitor-troubleshoot>
+ Upgrade Monitoring </upgrade/upgrade-monitor/index>
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+
+
+.. include:: /operating-scylla/monitoring/_common/note-versions.rst
+
+.. include:: /operating-scylla/monitoring/_common/monitor-description.rst
+
+.. panel-box::
+ :title: Monitoring Scylla
+ :id: "monitoring"
+ :class: my-panel
+
+
+
+ * :doc:`Scylla Monitoring Stack <monitoring-stack>`
+ * :doc:`Scylla Monitoring Interfaces<monitoring-apis>`
+ * :doc:`Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>`
+ * :doc:`Troubleshoot Monitoring<monitor-troubleshoot>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Upgrade Guide - Monitoring </upgrade/upgrade-monitor/index>`
+ * Download the Scylla Monitoring :download:`Cheatsheet </operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf>`
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
@@ -0,0 +1,24 @@
+Minimal Production System Recommendations
+-----------------------------------------
+
+* **CPU** - at least 2 physical cores/ 4vCPUs
+* **Memory** - 15GB+ DRAM
+* **Disk** - persistent disk storage is proportional to the number of cores and Prometheus retention period (see the following section)
+* **Network** - 1GbE/10GbE preferred
+
+Calculating Prometheus Minimal Disk Space requirement
+.....................................................
+
+Prometheus storage disk performance requirements: persistent block volume, for example an EC2 EBS volume
+
+Prometheus storage disk volume requirement: proportional to the number of metrics it holds. The default retention period is 15 days, and the disk requirement is around 200MB per core, assuming the default scraping interval of 15s.
+
+For example, when monitoring a 6 node Scylla cluster, each with 16 CPU cores, and using the default 15 days retention time, you will need **minimal** disk space of
+
+.. code::
+
+ 6 * 16 * 200MB ~ 20GB
+
+
+To account for unexpected events, like replacing or adding nodes, we recommend allocating at least x4-5 space, in this case, ~100GB.
+Prometheus Storage disk does not have to be as fast as Scylla disk, and EC2 EBS, for example, is fast enough and provide HA out of the box.
diff --git a/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
@@ -0,0 +1,156 @@
+Troubleshoot Monitoring
+========================
+
+
+This document describes steps that needed to be done to troubleshoot monitoring problems when using `Grafana/Prometheus`_ monitoring tool.
+
+.. _`Grafana/Prometheus`: /monitoring_apis/
+
+Problem
+~~~~~~~
+
+
+
+No Data Points
+^^^^^^^^^^^^^^
+
+``No data points`` on all data charts.
+
+Solution
+........
+If there are no data points, or if a node appears to be unreachable when you know it is, the immediate suspect is the Prometheus connectivity.
+
+Start by login to the Prometheus console:
+
+point your browser to ``http://{ip}:9090`` ({ip} is the Prometheus ip address).
+
+Go to the target tabs: ``http://{ip}:9090/targets`` and see if any of the targets is down and if there is an error message.
+
+* Not using the local network for local ip range
+
+When using Docker containers, by default, the local ip range (127.0.0.X) is inside the Docker container and not the host local address,
+if you are trying to connect to a target via the local ip range from inside a Docker container, you need to use the ``-l`` flag to enable local network stack.
+
+
+* Prometheus may be pointing to the wrong target. Check your ``prometheus/scylla_servers.yml`` and ``prometheus/node_exporter_servers.yml``. Make sure in both cases Prometheus is pulling data from the Scylla server.
+
+Or
+
+* Your dashboard and Scylla version may not be aligned. If you are running Scylla 2.0.x, you need to start the monitoring server with ``./start-all.sh``.
+
+For example:
+
+.. code-block:: shell
+
+ ./start-all.sh -v 2.0.1
+
+More on start-all.sh `options`_.
+
+.. _`options`: /monitoring_stack/
+
+
+Grafana Chart Shows Error (!) Sign
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run this procedure on the Monitoring server.
+
+All of Grafana chart shows error (!) sign.
+There is a problem with the connection between Grafana and Prometheus. On the monitoring server:
+
+Solution
+.........
+
+1. Check Prometheus is running using ``sudo docker ps``.
+If it is not running check the ``prometheus.yml`` for errors.
+
+For example:
+
+.. code-block:: shell
+
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 41bd3db26240 monitor "/docker-entrypoin..." 25 seconds ago Up 23 seconds 7000-7001/tcp, 9042/tcp, 9160/tcp, 9180/tcp, 10000/tcp monitor
+
+2. If it is running, go to "Data Source" in the Grafana GUI, choose Prometheus and click Test Connection.
+
+Grafana Shows Server Level Metrics, but not Scylla Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana shows server level metrics like disk usage, but not Scylla metrics.
+Prometheus fails to fetch metrics from Scylla servers.
+
+Solution
+.........
+
+* use ``curl <scylla_node>:9180/metrics`` to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+For example
+
+.. code-block:: shell
+
+ curl 172.17.0.2:9180/metrics
+
+Grafana Shows Scylla Metrics, but not Server Level Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana dashboard shows Scylla metrics, such as load, but not server metrics like disk usage.
+Prometheus fail to fetch metrics from ``node_exporter``.
+
+Solution
+.........
+
+1. Make sure ``node_exporter`` is running on each Scylla server. ``node_exporter`` is installed by ``scylla_setup``.
+If it does not, make sure to install and run it.
+
+2. If it is running, use ``curl <scylla_node>:9100/metrics`` (where 172.17.0.2 is a Scylla server IP) to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+Notice to users upgrading to Scylla Open Source 3.0 or Scylla Enterprise 2019.1
+................................................................................
+
+While upgrading you need to upgrade the ``node_exporter`` from 0.14 to 0.17 version.
+
+If the node_exporter service is not starting it may be that it needs to be updated manually.
+
+Check the node_exporter version ``node_exporter --version`` if it shows 0.14 check the node_exporter section
+in the `upgrade guide`_.
+
+.. _`upgrade guide`: /upgrade/upgrade-opensource/upgrade-guide-from-2.3-to-3.0/
+
+
+
+Working with wire-shark
+^^^^^^^^^^^^^^^^^^^^^^^
+
+No metrics shown in Scylla monitor.
+
+1. Install `wire-shark`_
+
+.. _`wire-shark`: https://www.wireshark.org/#download
+
+2. Capture the traffic between Scylla monitor and Scylla node using the ``tshark`` command.
+``tshark -i <network interface name> -f "dst port 9180"``
+
+For example:
+
+.. code-block:: shell
+
+ tshark -i eth0 -f "dst port 9180"
+
+Capture from Scylla node towards Scylla monitor server.
+
+Scylla is running.
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 66 59212 > 9180 [ACK] Seq=317 Ack=78193 Win=158080 Len=0 TSval=79869679 TSecr=3347447210
+
+Scylla is not running
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 74 60440 > 9180 [SYN] Seq=0 Win=29200 Len=0 MSS=1460 SACK_PERM=1 TSval=79988291 TSecr=0 WS=128
+
+
+
+.. include:: /troubleshooting/_common/ts-return.rst
diff --git a/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
@@ -0,0 +1,370 @@
+Deploying Scylla Monitoring Without Docker
+==================================================================
+
+The following instructions will help to deploy :doc:`Scylla Monitoring Stack</operating-scylla/monitoring/2.2/monitoring-stack/>` in the case you can not use the docker version.
+
+Please note, Scylla recommends you use the docker version as it will provide you with most updated, current scylla monitoring system.
+
+.. include:: /operating-scylla/monitoring/2.2/min-prod-hw.rst
+
+The main item to set an alert on is the available disk space in the monitoring system. Data is indefinitely accrued on the Prometheus data directory. The current monitoring solution does not churn data.
+
+Install Scylla Monitor
+----------------------
+
+The following procedure is using a ``CentOS 7`` based instance
+
+1. Download the latest monitoring release.
+
+``wget https://github.com/scylladb/scylla-monitoring/archive/scylla-monitoring-2.2.tar.gz``
+
+
+2. open the tar
+
+``tar -xvf scylla-monitoring-2.2.tar.gz``
+
+Install Alertmanager
+--------------------
+
+Tested with alertmanager 0.16.0 version
+
+1. Install `alertmanager`_
+
+.. _`alertmanager` : https://prometheus.io/download/
+
+2. Copy the following file: ``rule_config.yml`` from ``scylla-monitoring-scylla-monitoring-2.2/prometheus`` directory to ``alertmanager.yml`` in the alertmanager installation directory.
+
+For example:
+
+.. code-block:: shell
+
+ cp -p /home/centos/scylla-monitoring-scylla-monitoring-2.2/prometheus/rule_config.yml /home/centos/alertmanager-0.16.0.linux-amd64/alertmanager.yml
+
+3. Start the Alertmanager
+
+For example:
+
+.. code-block:: shell
+
+ ./alertmanager
+
+
+4. Verify that Alertmanager is up and running, point your browser to the Alertmanager IP:Port
+
+For example:
+
+.. code-block:: shell
+
+ http://192.168.135.166:9093/
+
+.. image:: alertmanager.png
+
+
+Install Prometheus
+------------------
+
+Tested with prometheus 2.6.1 version
+
+1. Install `Prometheus`_
+
+.. _`Prometheus` : https://prometheus.io/download/
+
+2. Copy the following files: ``scylla_servers.yml``, ``node_exporter_servers.yml``, ``prometheus.rules.yml`` from ``scylla-monitoring-scylla-monitoring-2.2/prometheus`` directory to prometheus installation directory.
+
+Copy ``prometheus/prometheus.yml.template`` to ``prometheus.yml``
+
+For example:
+
+.. code-block:: shell
+
+ cp -p /home/centos/scylla-monitoring-scylla-monitoring-2.2/prometheus/*.yml /home/centos/prometheus-2.6.1.linux-amd64
+
+3. Edit the ``prometheus.yml`` file to point to the correct static data sources.
+
+.. note:: Make sure to include the ``honor_labels: false`` parameter in the prometheus.yml file.
+
+.. code-block:: shell
+
+ sudo vi /<prometheus_installation_location>/prometheus-2.6.1.linux-amd64/prometheus.yml
+
+Set the alertmanger address and port by replacing ``AM_ADDRESS`` in the file.
+
+For example if the alertmanager will run on the same host:
+
+.. code-block:: shell
+
+ alerting:
+ alertmanagers:
+ - static_configs:
+ - targets:
+ - 127.0.0.1:9093
+
+For example the scrap config for scylla:
+
+.. code-block:: shell
+
+ global:
+ scrape_interval: 5s # By default, scrape targets every 5 second.
+ scrape_timeout: 4s # Timeout before trying to scape a target again
+
+ # Attach these labels to any time series or alerts when communicating with
+ # external systems (federation, remote storage, Alertmanager).
+ external_labels:
+ monitor: 'scylla-monitor'
+
+ scrape_configs:
+ - job_name: scylla
+ honor_labels: false
+ file_sd_configs:
+ - files:
+ - /home/centos/prometheus-2.6.1.linux-amd64/scylla_servers.yml
+ relabel_configs:
+ - source_labels: [__address__]
+ regex: '(.*):.+'
+ target_label: instance
+ replacement: '${1}'
+
+
+4. Edit the, ``scylla_servers.yml``, ``node_exporter_servers.yml`` and ``scylla_manager_serer.yml`` files to point to your Scylla nodes.
+
+.. note::
+ With Scylla Monitoring version 2.2, you no longer need to configure ``node_exporter_server``. Instead, in the prometheus scrap config of the node_exporter
+ you can use the same file you used for scylla and Prometheus will assume you have a node_exporter running on each Scylla server.
+
+Add the labels for the cluster and data-center
+
+``scylla_servers.yml``:
+
+For example:
+
+.. code-block:: shell
+
+ cat scylla_servers.yml
+ # List Scylla end points
+
+ - targets:
+ - 192.168.66.6:9180
+ - 192.168.66.244:9180
+ labels:
+ cluster: cluster1
+ dc: dc1
+ - targets:
+ - 172.17.0.3:9180
+ labels:
+ cluster: cluster1
+ dc: dc2
+
+.. note::
+ See the previous note about deprecating the ``node_exporter_servers.yml`` file.
+
+``node_exporter_servers.yml``:
+
+For example:
+
+.. code-block:: shell
+
+ cat node_exporter_servers.yml
+ # List end points with node exporter
+
+ - targets:
+ - '192.168.66.6:9100'
+ - '192.168.66.244:9100'
+ labels:
+ cluster: cluster1
+ dc: dc1
+ - targets:
+ - 172.17.0.3:9100
+ labels:
+ cluster: cluster1
+ dc: dc2
+
+``scylla_manager_serer.yml``
+
+For example:
+
+.. code-block:: shell
+
+ - targets:
+ - 127.0.0.1:56090
+
+5. Create a data directory for prometheus to store the metrics data
+
+For example:
+
+.. code-block:: shell
+
+ sudo mkdir /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+
+6. Start Prometheus server:
+
+For example:
+
+.. code-block:: shell
+
+ sudo ./prometheus --config.file=prometheus.yml --storage.tsdb.path /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+Data should start accumulate on: /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+7. Verify that Prometheus is up and running, point your browser to the Prometheus IP:Port
+
+For example:
+
+.. code-block:: shell
+
+ http://192.168.135.166:9090/
+
+.. image:: 1.png
+
+Prometheus console should be visible
+
+8. Verify that the node_exporter and scylla metrics accumulating in the server by executing a query through the console
+
+For example:
+
+``node_memory_MemFree``
+
+.. image:: 2.png
+
+And
+
+``scylla_reactor_utilization``
+
+.. image:: 3.png
+
+At this point Scylla is emitting the metrics and Prometheus is able to store them.
+
+
+Install Grafana
+---------------
+
+1. Install Grafana base on the instructions `here`_ make sure to use version 5.0.0 or higher
+
+.. _`here` : http://docs.grafana.org/installation/
+
+Depends if you installed Grafana from a repository (yum install), or if you downloaded the zip version, the directory structure will be
+different in the rest of the steps.
+
+2. Access Scylla-Grafana-monitoring directory
+
+``cd /home/centos/scylla-monitoring-scylla-monitoring-2.2/``
+
+3. Copy the plugins to the grafana plugins directory (by default ``/var/lib/grafana/``)
+
+.. code-block:: shell
+
+ sudo cp -r grafana/plugins /var/lib/grafana/
+
+If you installed Grafana from packages, instead of ``/var/lib/grafana/`` you should copy it to ``public/app`` inside the directory you
+opened Grafana in.
+
+For example:
+
+.. code-block:: shell
+
+ cp -r grafana/plugins /home/centos/grafana-5.4.3/public/app
+
+4. Generate the dashboards you would like to load and provision them
+
+For example Scylla version 3.0 and Scylla Manager version 1.3
+
+.. code-block:: shell
+
+ ./generate-dashboards.sh -v 3.0 -M 1.3
+
+For Grafana installed with ``yum install``
+
+.. code-block:: shell
+
+ sudo cp grafana/provisioning/dashboards/load.* /etc/grafana/provisioning/dashboards/
+ sudo mkdir -p /var/lib/grafana/dashboards
+ sudo cp -r grafana/build/* /var/lib/grafana/dashboards
+
+For Grafana installed from packages
+
+.. code-block:: shell
+
+ cp -p -r grafana/build/* /home/centos/grafana-5.4.3/public/build/
+ cp -p grafana/provisioning/dashboards/load.* /home/centos/grafana-5.4.3/conf/provisioning/dashboards/
+
+Edit the ``load.*`` files in ``/home/centos/grafana-5.4.3/conf/provisioning/dashboards/`` for the correct path,
+for example ``load.3.0.yaml`` would point to: ``/home/centos/grafana-5.4.3/public/build/ver_3.0``
+
+
+5. Set the data source by copy ``datasource.yml`` and edit it
+
+.. code-block:: shell
+
+ sudo cp grafana/datasource.yml /etc/grafana/provisioning/datasources/
+
+For Grafana installed from packages
+
+.. code-block:: shell
+
+ cp -p grafana/datasource.yml /home/centos/grafana-5.4.3/conf/provisioning/datasources/
+
+You should set the prometheus and the alertmanager ip and port.
+
+For example
+
+.. code-block:: shell
+
+ sudo cat /etc/grafana/provisioning/datasources/datasource.yml
+ apiVersion: 1
+ datasources:
+ - name: prometheus
+ type: prometheus
+ url: http://192.168.135.167:9090
+ access: proxy
+ basicAuth: false
+
+ - name: alertmanager
+ type: camptocamp-prometheus-alertmanager-datasource
+ orgId: 1
+ typeLogoUrl: public/img/icn-datasource.svg
+ access: proxy
+ url: http://192.168.135.166:9093
+ password:
+ user:
+ database:
+ basicAuth:
+ isDefault:
+ jsonData:
+ severity_critical: '4'
+ severity_high: '3'
+ severity_warning: '2'
+ severity_info: '1'
+
+6. Start the Grafana service
+
+For Grafana installed with `yum install`
+
+``sudo service grafana-server start``
+
+For Grafana installed from packages:
+
+``cp -p /home/centos/grafana-5.4.3/conf/sample.ini /home/centos/grafana-5.4.3/conf/scylla.ini``
+
+Edit scylla.ini to reflect the right paths in the paths section of the file.
+
+
+.. code-block:: shell
+
+ plugins = /home/centos/grafana-5.4.3/public/app/plugins
+ provisioning = /home/centos/grafana-5.4.3/conf/provisioning
+
+
+Start the server:
+
+.. code-block:: shell
+
+ cd /home/centos/grafana-5.4.3/
+ ./bin/grafana-server -config /home/centos/grafana-5.4.3/conf/scylla.ini
+
+7. Make sure Grafana is running
+
+Point your browser to the Grafana server port 3000, the assumption is that Grafana and Prometheus are collocated on the same server.
+
+.. image:: grafana.png
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/monitor.png b/docs/operating-scylla/monitoring/2.2/monitor.png
--- a/docs/operating-scylla/monitoring/2.2/monitor.png
+++ b/docs/operating-scylla/monitoring/2.2/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
@@ -0,0 +1,47 @@
+
+Monitoring Interfaces
+=====================
+
+Scylla exposes two interfaces for online monitoring, as described below
+
+Prometheus
+----------
+By default, Scylla listen on port 9180 for `Prometheus <https://prometheus.io/>`_ requests. To connect a Prometheus server to scylla in your prometheus.yaml configuration file, add scylla as a target with :code:`your-ip:9180`
+
+For more information on monitoring Scylla with Prometheus see :doc:`Scylla Monitoring Stack <monitoring-stack/>`
+
+You can change Prometheus listening address and port in scylla.yaml file
+
+.. code-block:: yaml
+
+ # prometheus port
+ # By default, Scylla opens prometheus API port on port 9180
+ # setting the port to 0 will disable the prometheus API.
+ prometheus_port: 9180
+ #
+ # prometheus address
+ # By default, Scylla binds all interfaces to the prometheus API
+ # It is possible to restrict the listening address to a specific one
+ prometheus_address: 0.0.0.0
+
+Collectd
+--------
+
+Starting from Scylla version 2.3 `scyllatop <http://www.scylladb.com/2016/03/22/scyllatop/>`_ will not use Collectd any more.
+
+By default, Scylla send metrics to a local `Collectd <https://collectd.org/>`_ process, allowing you to watch Scylla status with `scyllatop <http://www.scylladb.com/2016/03/22/scyllatop/>`_. Scylla can also sends metric over Collectd protocol to external Collectd server, `Graphite <http://graphite.wikidot.com/>`_ or similar tools. To forward metrics to external server, update :code:`/etc/collectd.d/scylla.conf` to work as a proxy:
+
+.. code-block:: apacheconf
+
+ LoadPlugin network
+ <Plugin "network">
+ Listen "127.0.0.1" "25826"
+ Server "remote-ip" "25826"
+ Forward true
+ </Plugin>
+
+Where :code:`remote-ip` is the IP of your external Collectd server. Make sure to keep other elements of the file as is. Restart the collectd server for the new configuration to apply :code:`sudo service collectd restart`
+
+To change sample rate of Scylla metrics, update the :code:`SCYLLA_ARGS` line in :code:`/etc/sysconfig/scylla-server` file, parameter :code:`--collectd-poll-period 3000` (number in ms)
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
@@ -0,0 +1,168 @@
+Scylla Monitoring Stack
+=======================
+
+This document describes the setup of Scylla monitoring Stack, base on :doc:`Scylla Prometheus API <monitoring-apis>`.
+
+Scylla monitoring stack consists of three components, wrapped in Docker containers:
+
+* `prometheus` - collects and stores metrics
+* `alertmanager` - handles alerts
+* `grafana` - dashboard server
+
+.. image:: monitor.png
+
+The monitoring stack needs to be installed on a dedicated server, external to the Scylla cluster. Make sure the monitoring server have access to the Scylla nodes so that it can pull the metrics over the Prometheus API.
+
+For evaluation, you can run Scylla monitoring stack on any server (or laptop) that can handle two Docker instances at the same time. For production, see recommendation below.
+
+.. include:: min-prod-hw.rst
+
+
+Prerequisites
+.............
+
+* `docker`_
+
+.. _`docker`: https://www.docker.com/
+
+
+Procedure
+.........
+
+1. Download and extract the latest `Scylla Monitoring Stack binary`_; for example, for release 2.2.0
+
+.. _`Scylla Monitoring Stack binary`: https://github.com/scylladb/scylla-monitoring/releases
+
+.. code-block:: sh
+
+ wget https://github.com/scylladb/scylla-monitoring/archive/scylla-monitoring-2.2.tar.gz
+ tar -xvf scylla-monitoring-2.2.tar.gz
+ cd scylla-monitoring-scylla-monitoring-2.2
+
+As an alternative, you can clone and use the git repository directly.
+
+.. code-block:: sh
+
+ git clone https://github.com/scylladb/scylla-monitoring.git
+ cd scylla-monitoring
+ git checkout branch-2.2
+
+2. Start docker service if needed
+
+.. code-block:: sh
+
+ centos $ sudo service docker start
+ ubuntu $ sudo systemctl restart docker
+
+
+
+3. Update ``prometheus/scylla_servers.yml`` with the targets' IPs (the servers you wish to monitor).
+
+.. note::
+ It is important that the dc in the target files will match the datacenters names used by Scylla.
+ Use the ``nodetool status`` command to validate the datacenter names used by Scylla.
+
+For example:
+
+.. code-block:: yaml
+
+ targets:
+ - 172.17.0.2
+ - 172.17.0.3
+ labels:
+ cluster: cluster1
+ dc: dc1
+
+
+For general node information (disk, network, etc.) Scylla Monitoring Stack uses the node_exporter agent that runs on the same machine as Scylla does.
+By default, Prometheus will assume you have a node_exporter running on each machine. If this is not the case, you can override the node_exporter
+targets configuration file by creating an additional
+file and pass it with the ``-n`` flag.
+
+.. note::
+ By default, there is no need to configure ``node_exporter_server.yml``. Prometheus will use the same targets it uses for
+ Sylla and will assume you have a node_exporter
+ running on each Scylla server.
+
+
+It is possible to configure your own target file instead of updating ``scylla_servers.yml``, using the ``-s`` for scylla target file.
+
+For example:
+
+.. code-block:: yaml
+
+ ./start-all.sh -s my_scylla_server.yml -d data_dir
+
+
+Use Labels to mark different Data Centers
+
+As can be seen in the examples, each target has its own set of labels to mark the cluster name and the data center (dc).
+You can add multiple targets in the same file for multiple clusters or multiple data centers.
+
+4. Connect to `Scylla Manager`_ by updating ``prometheus/scylla_manager_servers.yml``
+If you are using Scylla Manager, you should set its ip.
+
+.. _`Scylla Manager`: /operating-scylla/manager/
+
+For example
+
+.. code-block:: yaml
+
+ # List Scylla Manager end points
+
+ - targets:
+ - 127.0.0.1:56090
+
+
+Note that you do not need to add labels to the Scylla Manager targets.
+
+
+Start and Stop
+..............
+
+Start
+
+.. code-block:: yaml
+
+ ./start-all.sh -d data_dir
+
+
+Stop
+
+.. code-block:: yaml
+
+ ./kill-all.sh
+
+Setting Specific Version
+........................
+
+By default, start-all.sh will start with dashboards for the latest two Scylla versions and the latest Scylla Manager version.
+
+You can specify specific scylla version with the ``-v`` flag and Scylla Manager version with ``-M`` flag
+
+For example:
+
+.. code-block:: sh
+
+ ./start-all.sh -v 3.0,master -M 1.3
+
+will load the dashboards for Scylla versions ``3.0`` and ``master`` and the dashboard for Scylla Manager ``1.3``
+
+View Grafana Monitor
+....................
+
+Point your browser to ``your-server-ip:3000``
+By default, Grafana authentication is disabled. To enable it and set a password for user admin use the ``-a`` option
+
+For example:
+
+.. code-block:: yaml
+
+ 10.10.0.1:3000
+
+* Choose Disk and network interface
+
+The dashboard holds a drop down menu at its upper left corner for disk and network interface.
+You should choose relevant disk and interface for the dashboard to show the graphs.
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/1.png b/docs/operating-scylla/monitoring/2.3/1.png
--- a/docs/operating-scylla/monitoring/2.3/1.png
+++ b/docs/operating-scylla/monitoring/2.3/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/2.png b/docs/operating-scylla/monitoring/2.3/2.png
--- a/docs/operating-scylla/monitoring/2.3/2.png
+++ b/docs/operating-scylla/monitoring/2.3/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/3.png b/docs/operating-scylla/monitoring/2.3/3.png
--- a/docs/operating-scylla/monitoring/2.3/3.png
+++ b/docs/operating-scylla/monitoring/2.3/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/4.png b/docs/operating-scylla/monitoring/2.3/4.png
--- a/docs/operating-scylla/monitoring/2.3/4.png
+++ b/docs/operating-scylla/monitoring/2.3/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.3/alertmanager.png b/docs/operating-scylla/monitoring/2.3/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.3/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.3/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/cql-optimization.rst b/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
@@ -0,0 +1,138 @@
+The CQL Optimization Dashboard
+==============================
+
+The CQL Optimization Dashboard (introduce in Scylla monitoring 2.2) is a tool to help identify potentials issues with queries, data model and driver.
+
+.. figure:: cql_optimization_master.png
+
+ **The CQL Optimization Dashboard**
+
+The dashboard holds gauges and graphs. When inspecting the system, we like the gauge to be near zero and the graphs as low as possible.
+
+.. note:: Besides your queries, there are queries generated by the cql driver and internal queries to the system tables which can be misleading when testing with low traffic.
+
+The following sections describe each of the dashboard's panel
+
+Prepared Statements
+^^^^^^^^^^^^^^^^^^^
+
+:ref:`Prepared statements <prepared-statements>` are queries that are first defined as a template with place holders for the values and then that template is used
+multiple times with different values.
+
+Using prepared statements has the following benefits:
+
+* The database only needs to parse the query once
+* The driver can route the query to the right node
+* Using place-holders and values is safer and prevents CQL-Injection
+
+The **CQL Non-Prepared Queries** Gauge shows the percentage of queries that are not prepared.
+
+The **CQL Non-Prepared Queries** Graph shows the rate of the queries. Make sure both are low.
+
+Token Aware
+^^^^^^^^^^^
+
+Scylla is a distributed database, with each node contains only part of the data - a range of the token ring.
+Ideally, a query would reach the node that holds the data (one of the replicas), failing to do so would mean the coordinator
+will need to send the query internally to a replica, result with a higher latency,
+and more resources usage.
+
+Typically, your driver would know how to route the queries to a replication node, but using non-prepared statements, non-token-aware driver
+or load-balance can cause the query to reach a node that is not a replica.
+
+The **Non-Token Aware** Gauge shows the percentage of queries that reached a node that does not hold that data (a node that is not a replica-node).
+
+The **Non-Token Aware Queries** Graph shows the rate of the queries that did not reach a replica-node, make sure both are low.
+
+Paged Queries
+^^^^^^^^^^^^^
+
+By default, read queries are paged, this means that Scylla will break the results into multiple chunks limiting the reply size.
+Non-Paged queries require all results be returned in one result increasing the overall load of the system and clients and should be avoided.
+
+The **Non-Paged CQL Reads** Gauge shows the percentage of non-paged read queries that did not use paging.
+
+The **Non-Paged CQL Reads** Graph shows the rate of the non-paged queries, make sure both are low.
+
+
+Reversed CQL Reads
+^^^^^^^^^^^^^^^^^^
+
+Scylla supports compound primary keys with a clustering column, this kind of primary keys allows an efficient way
+to return sorted results that are sorted by the clustering column.
+
+Querying with an order different than the order the ``CLUSTERING ORDER BY`` was defined is inefficient and should be avoided.
+
+For example, look at the following table:
+
+.. code-block:: shell
+
+ CREATE TABLE ks1.table_demo (
+ category text,
+ type int,
+ PRIMARY KEY (category, type))
+ WITH CLUSTERING ORDER BY (type DESC);
+
+
+The following query uses reverse order:
+
+.. code-block:: shell
+
+ select * from ks1.table_demo where category='cat1' order by type ASC;
+
+The **Reversed CQL Reads** Gauge shows the percentage of read queries that use ``ORDER BY`` that is different than the ``CLUSTERING ORDER BY``.
+
+The **Reversed CQL Reads** Graph shows the rate of the read queries that use ``ORDER BY`` that is different than the ``CLUSTERING ORDER BY``, make sure both are low.
+
+ALLOW FILTERING
+^^^^^^^^^^^^^^^
+
+Scylla supports server side data filtering that is not based on the primary key. This means Scylla would read data and then filter and
+return part of it to the user. Data that is read and then filtered is an overhead to the system.
+
+These kinds of queries can create a big load on the system, and should be used with care.
+
+The CQL optimization dashboard, check for two things related to queries that use ``ALLOW FILTERING`` how many such queries exist and how much of the data that was read was
+dropped before returning to the client.
+
+The **ALLOW FILTERING CQL Reads** Gauge shows the percentage of read queries that use ``ALLOW FILTERING``.
+
+The **ALLOW FILTERING CQL Reads** Graph shows the rate of the read queries that use ``ALLOW FILTERING``, make sure both are low.
+
+The **ALLOW FILTERING Filtered Rows** Gauge shows the percentage of rows that were read and then filtered, this is an indication of the additional overhead to the system.
+
+The **ALLOW FILTERING Filtered Rows** Graph shows multiple graphs: the rows that were read, the rows that matched and the rows that were dropped. Rows that
+were dropped are an additional overhead to the system.
+
+Cross DC read requests
+^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+ The CQL Optimization Dashboard relies on the definition of nodes per Data Center in the Monitoring Stack (prometheus/scylla_servers.yml) to match the Data Center names used in Scylla Cluster.
+ If this is not the case, you will see the wrong result.
+
+In a typical situation, a client performs a read from the nearest data-center and that query is performed local to the data-center.
+A read request that ends up causing traffic between data-centers adds additional overhead to the system.
+
+The **Cross DC read requests** Gauge shows the percentage of read queries that caused a request to an external data-center, make sure it is low or zero.
+
+
+Available from Scylla Monitoring Version 2.3
+********************************************
+Cross shard
+^^^^^^^^^^^
+Scylla uses a shared-nothing model that shards all requests onto individual cores. Scylla runs one application thread-per-core, and depends on explicit message passing, not shared memory between threads.
+This design avoids slow, unscalable lock primitives and cache bounces.
+
+Ideally, each request to a Scylla node reaches the right core (shard), avoiding internal communication between cores.
+This is not always the case, for example, when using a non-shard-aware Scylla driver (see more here_)
+
+.. _here: /using-scylla/drivers/index/
+
+New panels in the CQL Optimization dashboard were added to help identify cross-shard traffic.
+
+The **Cross Shard** Gauge shows the percentage of queries that reach a shard that does not hold the data.
+
+The **Cross Shard Queries** Graph shows the rate of the queries that did not reach a shard with the data, make sure both are low.
+
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/grafana.png b/docs/operating-scylla/monitoring/2.3/grafana.png
--- a/docs/operating-scylla/monitoring/2.3/grafana.png
+++ b/docs/operating-scylla/monitoring/2.3/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/index.rst b/docs/operating-scylla/monitoring/2.3/index.rst
--- a/docs/operating-scylla/monitoring/2.3/index.rst
+++ b/docs/operating-scylla/monitoring/2.3/index.rst
@@ -0,0 +1,35 @@
+:orphan:
+Scylla Monitoring 2.3
+=====================
+
+.. toctree::
+ :hidden:
+
+ Scylla Monitoring Stack <monitoring-stack>
+ Scylla Monitoring Interfaces <monitoring-apis>
+ Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>
+ Troubleshoot Monitoring <monitor-troubleshoot>
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+ Upgrade Monitoring </upgrade/upgrade-monitor/index>
+ CQL Optimization Dashboard <cql-optimization>
+ Adding and Modifying Dashboards <updating-dashboard>
+
+.. include:: /operating-scylla/monitoring/_common/note-versions.rst
+
+.. include:: /operating-scylla/monitoring/_common/monitor-description.rst
+
+.. panel-box::
+ :title: Monitoring Scylla
+ :id: "monitoring"
+ :class: my-panel
+
+ * :doc:`Scylla Monitoring Stack <monitoring-stack>`
+ * :doc:`Scylla Monitoring Interfaces<monitoring-apis>`
+ * :doc:`Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>`
+ * :doc:`Troubleshoot Monitoring<monitor-troubleshoot>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Upgrade Guide - Monitoring </upgrade/upgrade-monitor/index>`
+ * Download the Scylla Monitoring :download:`Cheatsheet </operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf>`
+ * :doc:`CQL Optimization Dashboard <cql-optimization>`
+ * :doc:`Adding and Modifying Dashboards <updating-dashboard>`
+
diff --git a/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
@@ -0,0 +1,24 @@
+Minimal Production System Recommendations
+-----------------------------------------
+
+* **CPU** - at least 2 physical cores/ 4vCPUs
+* **Memory** - 15GB+ DRAM
+* **Disk** - persistent disk storage is proportional to the number of cores and Prometheus retention period (see the following section)
+* **Network** - 1GbE/10GbE preferred
+
+Calculating Prometheus Minimal Disk Space requirement
+.....................................................
+
+Prometheus storage disk performance requirements: persistent block volume, for example an EC2 EBS volume
+
+Prometheus storage disk volume requirement: proportional to the number of metrics it holds. The default retention period is 15 days, and the disk requirement is around 200MB per core, assuming the default scraping interval of 15s.
+
+For example, when monitoring a 6 node Scylla cluster, each with 16 CPU cores, and using the default 15 days retention time, you will need **minimal** disk space of
+
+.. code::
+
+ 6 * 16 * 200MB ~ 20GB
+
+
+To account for unexpected events, like replacing or adding nodes, we recommend allocating at least x4-5 space, in this case, ~100GB.
+Prometheus Storage disk does not have to be as fast as Scylla disk, and EC2 EBS, for example, is fast enough and provide HA out of the box.
diff --git a/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
@@ -0,0 +1,154 @@
+Troubleshoot Monitoring
+========================
+
+
+This document describes steps that needed to be done to troubleshoot monitoring problems when using `Grafana/Prometheus`_ monitoring tool.
+
+.. _`Grafana/Prometheus`: /monitoring_apis/
+
+Problem
+~~~~~~~
+
+
+
+No Data Points
+^^^^^^^^^^^^^^
+
+``No data points`` on all data charts.
+
+Solution
+........
+If there are no data points, or if a node appears to be unreachable when you know it is, the immediate suspect is the Prometheus connectivity.
+
+Start by login to the Prometheus console:
+
+point your browser to ``http://{ip}:9090`` ({ip} is the Prometheus ip address).
+
+Go to the target tabs: ``http://{ip}:9090/targets`` and see if any of the targets is down and if there is an error message.
+
+* Not using the local network for local ip range
+
+When using Docker containers, by default, the local ip range (127.0.0.X) is inside the Docker container and not the host local address,
+if you are trying to connect to a target via the local ip range from inside a Docker container, you need to use the ``-l`` flag to enable local network stack.
+
+
+* Prometheus may be pointing to the wrong target. Check your ``prometheus/scylla_servers.yml`` and ``prometheus/node_exporter_servers.yml``. Make sure in both cases Prometheus is pulling data from the Scylla server.
+
+Or
+
+* Your dashboard and Scylla version may not be aligned. If you are running Scylla 2.0.x, you need to start the monitoring server with ``./start-all.sh``.
+
+For example:
+
+.. code-block:: shell
+
+ ./start-all.sh -v 2.0.1
+
+More on start-all.sh `options`_.
+
+.. _`options`: /monitoring_stack/
+
+
+Grafana Chart Shows Error (!) Sign
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run this procedure on the Monitoring server.
+
+All of Grafana chart shows error (!) sign.
+There is a problem with the connection between Grafana and Prometheus. On the monitoring server:
+
+Solution
+.........
+
+1. Check Prometheus is running using ``sudo docker ps``.
+If it is not running check the ``prometheus.yml`` for errors.
+
+For example:
+
+.. code-block:: shell
+
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 41bd3db26240 monitor "/docker-entrypoin..." 25 seconds ago Up 23 seconds 7000-7001/tcp, 9042/tcp, 9160/tcp, 9180/tcp, 10000/tcp monitor
+
+2. If it is running, go to "Data Source" in the Grafana GUI, choose Prometheus and click Test Connection.
+
+Grafana Shows Server Level Metrics, but not Scylla Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana shows server level metrics like disk usage, but not Scylla metrics.
+Prometheus fails to fetch metrics from Scylla servers.
+
+Solution
+.........
+
+* use ``curl <scylla_node>:9180/metrics`` to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+For example
+
+.. code-block:: shell
+
+ curl 172.17.0.2:9180/metrics
+
+Grafana Shows Scylla Metrics, but not Server Level Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana dashboard shows Scylla metrics, such as load, but not server metrics like disk usage.
+Prometheus fail to fetch metrics from ``node_exporter``.
+
+Solution
+.........
+
+1. Make sure ``node_exporter`` is running on each Scylla server. ``node_exporter`` is installed by ``scylla_setup``.
+If it does not, make sure to install and run it.
+
+2. If it is running, use ``curl <scylla_node>:9100/metrics`` (where 172.17.0.2 is a Scylla server IP) to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+Notice to users upgrading to Scylla Open Source 3.0 or Scylla Enterprise 2019.1
+................................................................................
+
+While upgrading you need to upgrade the ``node_exporter`` from 0.14 to 0.17 version.
+
+If the node_exporter service is not starting it may be that it needs to be updated manually.
+
+Check the node_exporter version ``node_exporter --version`` if it shows 0.14 check the node_exporter section
+in the `upgrade guide`_.
+
+.. _`upgrade guide`: /upgrade/upgrade-opensource/upgrade-guide-from-2.3-to-3.0/
+
+
+
+Working with wire-shark
+^^^^^^^^^^^^^^^^^^^^^^^
+
+No metrics shown in Scylla monitor.
+
+1. Install `wire-shark`_
+
+.. _`wire-shark`: https://www.wireshark.org/#download
+
+2. Capture the traffic between Scylla monitor and Scylla node using the ``tshark`` command.
+``tshark -i <network interface name> -f "dst port 9180"``
+
+For example:
+
+.. code-block:: shell
+
+ tshark -i eth0 -f "dst port 9180"
+
+Capture from Scylla node towards Scylla monitor server.
+
+Scylla is running.
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 66 59212 > 9180 [ACK] Seq=317 Ack=78193 Win=158080 Len=0 TSval=79869679 TSecr=3347447210
+
+Scylla is not running
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 74 60440 > 9180 [SYN] Seq=0 Win=29200 Len=0 MSS=1460 SACK_PERM=1 TSval=79988291 TSecr=0 WS=128
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitor.png b/docs/operating-scylla/monitoring/2.3/monitor.png
--- a/docs/operating-scylla/monitoring/2.3/monitor.png
+++ b/docs/operating-scylla/monitoring/2.3/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst b/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/1.png b/docs/operating-scylla/monitoring/2.4/1.png
--- a/docs/operating-scylla/monitoring/2.4/1.png
+++ b/docs/operating-scylla/monitoring/2.4/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/2.png b/docs/operating-scylla/monitoring/2.4/2.png
--- a/docs/operating-scylla/monitoring/2.4/2.png
+++ b/docs/operating-scylla/monitoring/2.4/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/3.png b/docs/operating-scylla/monitoring/2.4/3.png
--- a/docs/operating-scylla/monitoring/2.4/3.png
+++ b/docs/operating-scylla/monitoring/2.4/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/4.png b/docs/operating-scylla/monitoring/2.4/4.png
--- a/docs/operating-scylla/monitoring/2.4/4.png
+++ b/docs/operating-scylla/monitoring/2.4/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.4/alertmanager.png b/docs/operating-scylla/monitoring/2.4/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.4/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.4/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/cql-optimization.rst b/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/grafana.png b/docs/operating-scylla/monitoring/2.4/grafana.png
--- a/docs/operating-scylla/monitoring/2.4/grafana.png
+++ b/docs/operating-scylla/monitoring/2.4/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/index.rst b/docs/operating-scylla/monitoring/2.4/index.rst
--- a/docs/operating-scylla/monitoring/2.4/index.rst
+++ b/docs/operating-scylla/monitoring/2.4/index.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor.png b/docs/operating-scylla/monitoring/2.4/monitor.png
--- a/docs/operating-scylla/monitoring/2.4/monitor.png
+++ b/docs/operating-scylla/monitoring/2.4/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst b/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/1.png b/docs/operating-scylla/monitoring/3.0/1.png
--- a/docs/operating-scylla/monitoring/3.0/1.png
+++ b/docs/operating-scylla/monitoring/3.0/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/2.png b/docs/operating-scylla/monitoring/3.0/2.png
--- a/docs/operating-scylla/monitoring/3.0/2.png
+++ b/docs/operating-scylla/monitoring/3.0/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/3.png b/docs/operating-scylla/monitoring/3.0/3.png
--- a/docs/operating-scylla/monitoring/3.0/3.png
+++ b/docs/operating-scylla/monitoring/3.0/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/4.png b/docs/operating-scylla/monitoring/3.0/4.png
--- a/docs/operating-scylla/monitoring/3.0/4.png
+++ b/docs/operating-scylla/monitoring/3.0/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/alertmanager.png b/docs/operating-scylla/monitoring/3.0/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.0/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.0/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/cql-optimization.rst b/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/grafana.png b/docs/operating-scylla/monitoring/3.0/grafana.png
--- a/docs/operating-scylla/monitoring/3.0/grafana.png
+++ b/docs/operating-scylla/monitoring/3.0/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/index.rst b/docs/operating-scylla/monitoring/3.0/index.rst
--- a/docs/operating-scylla/monitoring/3.0/index.rst
+++ b/docs/operating-scylla/monitoring/3.0/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/1.png b/docs/operating-scylla/monitoring/3.1/1.png
--- a/docs/operating-scylla/monitoring/3.1/1.png
+++ b/docs/operating-scylla/monitoring/3.1/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/2.png b/docs/operating-scylla/monitoring/3.1/2.png
--- a/docs/operating-scylla/monitoring/3.1/2.png
+++ b/docs/operating-scylla/monitoring/3.1/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/3.png b/docs/operating-scylla/monitoring/3.1/3.png
--- a/docs/operating-scylla/monitoring/3.1/3.png
+++ b/docs/operating-scylla/monitoring/3.1/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/4.png b/docs/operating-scylla/monitoring/3.1/4.png
--- a/docs/operating-scylla/monitoring/3.1/4.png
+++ b/docs/operating-scylla/monitoring/3.1/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/alertmanager.png b/docs/operating-scylla/monitoring/3.1/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.1/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.1/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/cql-optimization.rst b/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/grafana.png b/docs/operating-scylla/monitoring/3.1/grafana.png
--- a/docs/operating-scylla/monitoring/3.1/grafana.png
+++ b/docs/operating-scylla/monitoring/3.1/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/index.rst b/docs/operating-scylla/monitoring/3.1/index.rst
--- a/docs/operating-scylla/monitoring/3.1/index.rst
+++ b/docs/operating-scylla/monitoring/3.1/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/1.png b/docs/operating-scylla/monitoring/3.2/1.png
--- a/docs/operating-scylla/monitoring/3.2/1.png
+++ b/docs/operating-scylla/monitoring/3.2/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/2.png b/docs/operating-scylla/monitoring/3.2/2.png
--- a/docs/operating-scylla/monitoring/3.2/2.png
+++ b/docs/operating-scylla/monitoring/3.2/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/3.png b/docs/operating-scylla/monitoring/3.2/3.png
--- a/docs/operating-scylla/monitoring/3.2/3.png
+++ b/docs/operating-scylla/monitoring/3.2/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/4.png b/docs/operating-scylla/monitoring/3.2/4.png
--- a/docs/operating-scylla/monitoring/3.2/4.png
+++ b/docs/operating-scylla/monitoring/3.2/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/alerting.rst b/docs/operating-scylla/monitoring/3.2/alerting.rst
--- a/docs/operating-scylla/monitoring/3.2/alerting.rst
+++ b/docs/operating-scylla/monitoring/3.2/alerting.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/alertmanager.png b/docs/operating-scylla/monitoring/3.2/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.2/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.2/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/cql-optimization.rst b/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/grafana.png b/docs/operating-scylla/monitoring/3.2/grafana.png
--- a/docs/operating-scylla/monitoring/3.2/grafana.png
+++ b/docs/operating-scylla/monitoring/3.2/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/index.rst b/docs/operating-scylla/monitoring/3.2/index.rst
--- a/docs/operating-scylla/monitoring/3.2/index.rst
+++ b/docs/operating-scylla/monitoring/3.2/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring_stack.png b/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
--- a/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
+++ b/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/start-all.rst b/docs/operating-scylla/monitoring/3.2/start-all.rst
--- a/docs/operating-scylla/monitoring/3.2/start-all.rst
+++ b/docs/operating-scylla/monitoring/3.2/start-all.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/1.png b/docs/operating-scylla/monitoring/3.3/1.png
--- a/docs/operating-scylla/monitoring/3.3/1.png
+++ b/docs/operating-scylla/monitoring/3.3/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/2.png b/docs/operating-scylla/monitoring/3.3/2.png
--- a/docs/operating-scylla/monitoring/3.3/2.png
+++ b/docs/operating-scylla/monitoring/3.3/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/3.png b/docs/operating-scylla/monitoring/3.3/3.png
--- a/docs/operating-scylla/monitoring/3.3/3.png
+++ b/docs/operating-scylla/monitoring/3.3/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/4.png b/docs/operating-scylla/monitoring/3.3/4.png
--- a/docs/operating-scylla/monitoring/3.3/4.png
+++ b/docs/operating-scylla/monitoring/3.3/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/alerting.rst b/docs/operating-scylla/monitoring/3.3/alerting.rst
--- a/docs/operating-scylla/monitoring/3.3/alerting.rst
+++ b/docs/operating-scylla/monitoring/3.3/alerting.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/alertmanager.png b/docs/operating-scylla/monitoring/3.3/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.3/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.3/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/cql-optimization.rst b/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
null
Committer: Anna Stuchlik <anna.s...@scylladb.com>
Branch: next
doc: move the documentation from the scylla-docs repo
---
diff --git a/docs/_static/img/mascots/scylla-cloud.svg b/docs/_static/img/mascots/scylla-cloud.svg
--- a/docs/_static/img/mascots/scylla-cloud.svg
+++ b/docs/_static/img/mascots/scylla-cloud.svg
@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="11.07 9.95 339.72 238.43"><defs><style>.cls-1,.cls-5,.cls-7,.cls-8{fill:#fff;}.cls-2,.cls-6{fill:#3b2d55;}.cls-3,.cls-4{fill:#57d1e5;}.cls-3,.cls-5,.cls-6,.cls-7,.cls-8{stroke:#3b2d55;}.cls-3,.cls-5,.cls-7,.cls-8{stroke-linecap:round;stroke-linejoin:round;}.cls-3,.cls-5{stroke-width:3.73px;}.cls-6{stroke-miterlimit:10;stroke-width:1.38px;}.cls-7{stroke-width:3.11px;}.cls-8{stroke-width:3.95px;}</style></defs><title>scylla-cloud</title><path class="cls-1" d="M81.4,125h-.18a17.09,17.09,0,0,1-.41-34.16v-.38A34.23,34.23,0,0,1,122.88,57.2a51.12,51.12,0,0,1,101.49-.54,34.46,34.46,0,0,1,5.06-.37,34.11,34.11,0,0,1,29.65,17.16c.61,0,1.19-.07,1.75-.07a25.83,25.83,0,0,1,0,51.65H81.4Z"/><path class="cls-2" d="M173.66,14a49.16,49.16,0,0,1,49,45A32.2,32.2,0,0,1,258,75.54a24.21,24.21,0,0,1,2.85-.19,23.85,23.85,0,0,1,0,47.7H81.4a15.12,15.12,0,0,1,.12-30.23c.46,0,.92,0,1.36.07-.06-.8-.1-1.6-.1-2.41a32.23,32.23,0,0,1,41.85-30.75,49.15,49.15,0,0,1,49-45.76m0-4A53.11,53.11,0,0,0,121.2,54.84a36.63,36.63,0,0,0-6.2-.53A36.21,36.21,0,0,0,78.86,89.06,19.07,19.07,0,0,0,81.13,127h179.8a27.8,27.8,0,0,0-.1-55.6h-.66a36.09,36.09,0,0,0-30.74-17.1c-1.12,0-2.25,0-3.38.16A53.09,53.09,0,0,0,173.66,10Z"/><path class="cls-3" d="M59.44,230.56a11.46,11.46,0,0,1-9.54,13.15,11.58,11.58,0,0,1-13.16-8.81S15.58,136.53,15.58,116.38c0-42.09,33.73-71.79,81.22-71.79S178,74.29,178,116.38c0,20.15-21.17,118.52-21.17,118.52a11.58,11.58,0,0,1-13.15,8.81,11.46,11.46,0,0,1-9.55-13.15"/><path class="cls-4" d="M151.64,202.37l-5.77,32A11.57,11.57,0,0,1,123,231"/><path class="cls-2" d="M152.86,202.59c-.4,2.81-.84,5.61-1.27,8.42l-1.34,8.4c-.44,2.8-.93,5.59-1.39,8.39l-.7,4.19-.35,2.1c-.06.35-.11.69-.21,1.11a10.07,10.07,0,0,1-.31,1.2,13.42,13.42,0,0,1-10.68,9.23,13.51,13.51,0,0,1-13.08-5.41,13.29,13.29,0,0,1-2.38-9.4,1.86,1.86,0,0,1,3.7.43h0a9.7,9.7,0,0,0,7.63,10.43,9.9,9.9,0,0,0,6.85-1.05,9.5,9.5,0,0,0,4.39-5.37c.33-1,.56-2.56.84-3.92l.81-4.18c.54-2.78,1.06-5.57,1.62-8.35l1.68-8.34c.58-2.78,1.14-5.56,1.75-8.33a1.24,1.24,0,0,1,2.44.44Z"/><ellipse class="cls-5" cx="69.31" cy="108.95" rx="36.24" ry="35.9"/><path class="cls-6" d="M76.8,85.43c-6.24,1.24-7.49,14.86-3.74,18.57,2.46,2.44,7.49,3.25,7.49,5s-5,2.51-7.49,5c-3.75,3.72-2.5,17.33,3.74,18.57C84.26,134,95.55,125,95.55,109S84.26,84,76.8,85.43Z"/><path class="cls-7" d="M51.81,157.22c1.25,3.72,5,9.91,10,8.67,2.42-.6,3.75-3.71,3.75-8.67"/><path class="cls-5" d="M84.3,154.75c1.25,4.95,2.5,8.66,6.25,8.66s8.75-4.95,7.5-13.61"/><path class="cls-2" d="M44.54,154.45a97.45,97.45,0,0,0,35.9-1.58,96.56,96.56,0,0,0,32.8-14.52,1.87,1.87,0,0,1,2.12,3.08h0a100.34,100.34,0,0,1-71.25,16.08,1.55,1.55,0,0,1,.45-3.07Z"/><path class="cls-2" d="M116,144.26a7.83,7.83,0,0,0-2.53-4.35,7.6,7.6,0,0,0-2.11-1.31A7.82,7.82,0,0,0,109,138a1.87,1.87,0,0,1,.31-3.72l.19,0h0a11.62,11.62,0,0,1,3.36,1.2,10.84,10.84,0,0,1,5.59,8.38,1.25,1.25,0,0,1-2.46.37Z"/><path class="cls-4" d="M70.59,231a11.56,11.56,0,0,1-22.86,3.38l-5.78-32"/><path class="cls-2" d="M72.44,230.81a13.22,13.22,0,0,1-2.37,9.4,13.51,13.51,0,0,1-8.14,5.3,13.46,13.46,0,0,1-15.62-9.11,10.11,10.11,0,0,1-.32-1.2c-.1-.42-.15-.76-.21-1.11L45.43,232l-.7-4.2c-.46-2.8-.94-5.59-1.39-8.39L42,211c-.42-2.81-.87-5.61-1.27-8.42a1.23,1.23,0,0,1,1.05-1.4,1.25,1.25,0,0,1,1.4,1c.6,2.77,1.16,5.55,1.74,8.33l1.68,8.34c.56,2.78,1.08,5.57,1.62,8.35l.81,4.17c.28,1.37.51,2.89.85,3.92a9.55,9.55,0,0,0,4.4,5.37,9.71,9.71,0,0,0,6.84,1.06,9.68,9.68,0,0,0,7.62-10.43h0a1.86,1.86,0,0,1,3.7-.44Z"/><path class="cls-4" d="M87.28,231.78a11.56,11.56,0,0,1-23,1.9l-3.14-27.6"/><path class="cls-2" d="M89.14,231.68a13.06,13.06,0,0,1-.5,4.56,13.45,13.45,0,0,1-26.26-2.45L62,229.86,61.22,222l-.7-7.87c-.23-2.63-.45-5.26-.64-7.89a1.24,1.24,0,0,1,2.47-.28c.4,2.6.77,5.22,1.15,7.83l1.07,7.83,1,7.85.51,3.92a9.54,9.54,0,0,0,.93,3.16,9.74,9.74,0,0,0,4.66,4.5,9.9,9.9,0,0,0,6.44.58A9.74,9.74,0,0,0,83.49,238a9.56,9.56,0,0,0,1.93-6.16v0a1.86,1.86,0,0,1,3.72-.17Z"/><path class="cls-4" d="M133,201.58l-3.64,32.1a11.57,11.57,0,0,1-23-1.9"/><path class="cls-2" d="M134.23,201.72c-.22,2.81-.48,5.63-.72,8.44l-.78,8.44-.84,8.43-.42,4.22-.22,2.11-.05.52-.09.61a10,10,0,0,1-.25,1.21,13.29,13.29,0,0,1-5.58,7.87,13.35,13.35,0,0,1-9.44,2.07,13.43,13.43,0,0,1-8.42-4.77,13.22,13.22,0,0,1-3-9.19,1.86,1.86,0,0,1,3.72.19h0a9.71,9.71,0,0,0,8.25,9.9,9.84,9.84,0,0,0,6.75-1.43,9.52,9.52,0,0,0,4.06-5.58,5.19,5.19,0,0,0,.19-.87l.07-.44.07-.52.27-2.1.53-4.21,1.07-8.4,1.13-8.4c.4-2.8.77-5.6,1.19-8.39a1.25,1.25,0,0,1,2.48.28Z"/><path class="cls-4" d="M109.29,200.55l-.94,32.18a11.56,11.56,0,0,1-23.11,0l-.94-32.18"/><path class="cls-2" d="M110.54,200.58q0,6.25-.05,12.49l-.06,6.24-.1,6.24-.1,6.25c0,.52,0,1-.06,1.65a12.37,12.37,0,0,1-.25,1.8,13.17,13.17,0,0,1-1.24,3.41,13.69,13.69,0,0,1-1,1.55,15.53,15.53,0,0,1-1.16,1.39,12.94,12.94,0,0,1-2.83,2.28,14.35,14.35,0,0,1-3.34,1.44,15.59,15.59,0,0,1-1.78.36c-.3,0-.61.08-.91.1l-.91,0a5.58,5.58,0,0,1-.91,0c-.3,0-.6,0-.9-.08a13.56,13.56,0,0,1-1.79-.38,13.15,13.15,0,0,1-3.34-1.43,13.4,13.4,0,0,1-4.94-5.22,13.82,13.82,0,0,1-1.25-3.41,16.6,16.6,0,0,1-.31-3.45l-.11-6.24-.1-6.25-.05-6.24q-.07-6.24,0-12.49a1.24,1.24,0,0,1,2.48-.07q.39,6.24.69,12.47l.31,6.23.26,6.24.26,6.24c0,.51,0,1.06.09,1.46a9.21,9.21,0,0,0,.2,1.28,9.67,9.67,0,0,0,4.51,6.11,9.92,9.92,0,0,0,3.65,1.26c.21,0,.43,0,.64.06a4.71,4.71,0,0,0,.65,0,9.69,9.69,0,0,0,8.53-5,9.09,9.09,0,0,0,.92-2.42,9.35,9.35,0,0,0,.2-1.29c0-.39.07-.94.09-1.46l.26-6.24.26-6.24.31-6.23q.28-6.24.68-12.47a1.24,1.24,0,0,1,1.32-1.17A1.26,1.26,0,0,1,110.54,200.58Z"/><path class="cls-1" d="M82.56,244.44H82.3A25.67,25.67,0,1,1,97.38,198a32.47,32.47,0,0,1,48-23.68,65.58,65.58,0,0,1,119-36.56,38.9,38.9,0,0,1,54.49,25.49,41.4,41.4,0,0,1-11.24,81.2h-225Z"/><path class="cls-2" d="M210.92,112.22a63.55,63.55,0,0,1,52.75,28.07,36.93,36.93,0,0,1,53.48,24.55,39.42,39.42,0,0,1-9.75,77.62H82.56v0H82.3A23.7,23.7,0,1,1,99,202,30.48,30.48,0,0,1,147.38,178c0-.71-.06-1.42-.06-2.13a63.6,63.6,0,0,1,63.6-63.6m0-4a67.55,67.55,0,0,0-67.4,62.91A34.46,34.46,0,0,0,96,194.73,27.65,27.65,0,1,0,82.3,246.41H307.63a43.38,43.38,0,0,0,12.79-84.75A40.88,40.88,0,0,0,265,135.29a67.51,67.51,0,0,0-54-27Z"/><path class="cls-8" d="M137.94,190.24c4.47-8.25,14.44-13.75,25.44-12.38"/><path class="cls-8" d="M236.78,145.33c12.08-3.17,26.49,1.5,35.17,13.43"/><path class="cls-8" d="M197.27,63.41c9.56-2.51,21,1.19,27.84,10.63"/></svg>
diff --git a/docs/_static/img/mascots/scylla-computer-headset.png b/docs/_static/img/mascots/scylla-computer-headset.png
--- a/docs/_static/img/mascots/scylla-computer-headset.png
+++ b/docs/_static/img/mascots/scylla-computer-headset.png
null
diff --git a/docs/_static/img/mascots/scylla-hardhat.png b/docs/_static/img/mascots/scylla-hardhat.png
--- a/docs/_static/img/mascots/scylla-hardhat.png
+++ b/docs/_static/img/mascots/scylla-hardhat.png
null
diff --git a/docs/_static/img/mascots/scylla-opensource.svg b/docs/_static/img/mascots/scylla-opensource.svg
--- a/docs/_static/img/mascots/scylla-opensource.svg
+++ b/docs/_static/img/mascots/scylla-opensource.svg
@@ -0,0 +1 @@
+<svg id="Calque_1" data-name="Calque 1" xmlns="http://www.w3.org/2000/svg" viewBox="16.52 39.95 169.48 207.72"><defs><style>.cls-1,.cls-2{fill:#57d1e5;}.cls-1,.cls-4,.cls-5{stroke:#3b2d55;stroke-linecap:round;stroke-linejoin:round;}.cls-1,.cls-4{stroke-width:3.7px;}.cls-3{fill:#3b2d55;}.cls-4,.cls-5{fill:#fff;}.cls-5{stroke-width:3.09px;}</style></defs><title>Plan de travail 1</title><path class="cls-1" d="M64.34,230a11.43,11.43,0,0,1-22.43,4.33S21,136.16,21,116.06c0-42,33.34-71.62,80.26-71.62s80.26,29.64,80.26,71.62c0,20.1-20.91,118.24-20.91,118.24A11.43,11.43,0,0,1,138.18,230"/><path class="cls-2" d="M155.46,201.85l-5.71,32a11.43,11.43,0,0,1-22.59-3.38"/><path class="cls-3" d="M156.67,202.06l-1.25,8.38-1.32,8.36-1.37,8.35-.69,4.17a41.44,41.44,0,0,1-.84,4.37,13.27,13.27,0,0,1-25.88-5.46,1.85,1.85,0,0,1,3.68.43,9.55,9.55,0,0,0,1.8,6.67,9.4,9.4,0,0,0,5.75,3.75,9.62,9.62,0,0,0,6.78-1.08,9.47,9.47,0,0,0,4.31-5.39c.31-1,.55-2.57.82-3.92l.8-4.16,1.61-8.31,1.65-8.3,1.72-8.29a1.23,1.23,0,0,1,2.43.43Z"/><circle class="cls-4" cx="74.1" cy="108.65" r="35.81"/><path class="cls-3" d="M81.5,85.19c-6.17,1.24-7.4,14.82-3.7,18.52,2.43,2.44,7.41,3.25,7.41,4.94s-5,2.51-7.41,4.94c-3.7,3.7-2.47,17.29,3.7,18.52,7.37,1.48,18.53-7.41,18.53-23.46S88.87,83.72,81.5,85.19Z"/><path class="cls-5" d="M56.81,156.81c1.23,3.7,4.94,9.88,9.88,8.64,2.39-.6,3.7-3.7,3.7-8.64"/><path class="cls-4" d="M88.91,154.34c1.24,4.94,2.47,8.64,6.18,8.64s8.64-4.94,7.41-13.58"/><path class="cls-3" d="M49.63,154.05A95.15,95.15,0,0,0,117.5,138a1.85,1.85,0,1,1,2.11,3h0a98.51,98.51,0,0,1-70.43,16,1.54,1.54,0,0,1,.46-3Z"/><path class="cls-3" d="M120.27,143.87a7.93,7.93,0,0,0-2.49-4.34,7.65,7.65,0,0,0-4.43-1.88,1.86,1.86,0,0,1,.28-3.7l.19,0h.05a11,11,0,0,1,6.09,3.37,10.58,10.58,0,0,1,2.75,6.18,1.22,1.22,0,0,1-1.11,1.34,1.24,1.24,0,0,1-1.33-1Z"/><path class="cls-2" d="M75.37,230.44a11.43,11.43,0,0,1-22.6,3.38l-5.7-32"/><path class="cls-3" d="M77.2,230.22a13.26,13.26,0,0,1-10.41,14.66,13.14,13.14,0,0,1-9.53-1.6,13.34,13.34,0,0,1-5.93-7.58,40.11,40.11,0,0,1-.85-4.37l-.69-4.18-1.37-8.35-1.32-8.36-1.25-8.38a1.23,1.23,0,0,1,2.43-.43L50,209.92l1.66,8.3,1.6,8.31.8,4.15c.27,1.36.51,2.89.82,3.92a9.58,9.58,0,0,0,18.65-3.93h0a1.85,1.85,0,0,1,3.67-.44Z"/><path class="cls-2" d="M91.86,231.18a11.42,11.42,0,0,1-22.76,1.9l-3.6-32"/><path class="cls-3" d="M93.71,231.08A13.27,13.27,0,0,1,82.43,245a13.16,13.16,0,0,1-9.38-2.15A13.33,13.33,0,0,1,67.57,235a34.51,34.51,0,0,1-.58-4.42l-.42-4.19-.83-8.4L65,209.6l-.7-8.41a1.23,1.23,0,0,1,2.45-.28l1.18,8.36L69,217.62,70.07,226l.53,4.18c.19,1.38.31,2.88.58,3.93A9.57,9.57,0,0,0,90,231.28h0a1.85,1.85,0,0,1,3.7-.19Z"/><path class="cls-2" d="M137,201.05l-3.6,32a11.43,11.43,0,0,1-22.77-1.9"/><path class="cls-3" d="M138.26,201.19l-.71,8.41-.77,8.39-.83,8.39-.41,4.2A38.06,38.06,0,0,1,135,235a13.27,13.27,0,0,1-23.22,5.24,13.42,13.42,0,0,1-2.93-9.15,1.86,1.86,0,0,1,2-1.73,1.84,1.84,0,0,1,1.73,1.93,9.6,9.6,0,0,0,2.22,6.52,9.49,9.49,0,0,0,5.94,3.38,9.68,9.68,0,0,0,6.69-1.47,9.43,9.43,0,0,0,4-5.61c.26-1,.39-2.55.57-3.93l.53-4.18,1.06-8.36,1.11-8.36,1.18-8.36a1.24,1.24,0,0,1,2.46.28Z"/><path class="cls-2" d="M113.61,200l-.93,32.1a11.42,11.42,0,0,1-22.84,0L88.91,200"/><path class="cls-3" d="M114.84,200.06q0,12.44-.19,24.87l-.1,6.22a17.8,17.8,0,0,1-.3,3.42,13.31,13.31,0,0,1-13,10.59,12.81,12.81,0,0,1-3.59-.5,12.62,12.62,0,0,1-3.32-1.46A13.38,13.38,0,0,1,89.49,238a13.15,13.15,0,0,1-1.22-3.4,17,17,0,0,1-.3-3.42l-.1-6.22q-.23-12.44-.19-24.87a1.24,1.24,0,0,1,2.47-.07c.49,8.28.92,16.56,1.24,24.84l.26,6.21a15.61,15.61,0,0,0,.27,2.75,9.55,9.55,0,0,0,9.35,7.48,9.49,9.49,0,0,0,8.44-5.05,9,9,0,0,0,.9-2.42,15.73,15.73,0,0,0,.27-2.76l.26-6.21c.32-8.28.75-16.56,1.23-24.84a1.24,1.24,0,0,1,2.47.07Z"/></svg>
diff --git a/docs/_utils/redirections.yaml b/docs/_utils/redirections.yaml
--- a/docs/_utils/redirections.yaml
+++ b/docs/_utils/redirections.yaml
@@ -0,0 +1,486 @@
+### a dictionary of redirections
+#old path: new path
+
+# removing redirection html script files
+cassandra-compatibility: /using-scylla/cassandra-compatibility
+getting-started/security: /operating-scylla/authorization
+getting-started/rbac_usecase: /operating-scylla/security/rbac-usecase
+operating-scylla/auditing: /operating-scylla/security/auditing
+operating-scylla/configure_ssl_on_live_scylla_cluster: /operating-scylla/security
+using-scylla/migrate: /procedures/cassandra_to_scylla_migration_process
+troubleshooting/performance_problem: /troubleshooting/report-scylla-problem
+
+#
+nodetool: /operating-scylla/nodetool
+procedures: /operating-scylla/procedures
+procedures/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+procedures/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+procedures/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+procedures/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+procedures/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+procedures/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+procedures/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+procedures/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+procedures/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+procedures/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+procedures/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+procedures/backup: /operating-scylla/procedures/backup-restore/backup
+procedures/restore: /operating-scylla/procedures/backup-restore/restore
+procedures/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+procedures/repair: /operating-scylla/procedures/maintenance/repair
+procedures/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+procedures/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+procedures/cassandra_to_scylla_migration_process: /operating-scylla/procedures/cassandra-to-scylla-migration-process
+procedures/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+admin: /operating-scylla/admin
+third-parties: /using-scylla/integrations
+system-configuration: /getting-started/system-configuration
+tls-ssl: /operating-scylla/security
+/operating-scylla/manager/manager-setup: /operating-scylla/manager
+/operating-scylla/manager/manager-cluster: /operating-scylla/manager
+/operating-scylla/manager/manager-overview: /operating-scylla/manager
+/operating-scylla/manager/manager-remote-datastore: /operating-scylla/manager
+/operating-scylla/manager/sctool: /operating-scylla/manager
+/operating-scylla/manager/1.2/manager-index: /operating-scylla/manager
+/operating-scylla/manager/2.0/restore: /operating-scylla/manager/2.0/restore-a-backup
+/operating-scylla/manager/2.0/overview: /operating-scylla/manager/2.0/architecture
+/operating-scylla/snitch: /operating-scylla/system-configuration/snitch
+/operating-scylla/troubleshooting/report_scylla_problem: /troubleshooting/report-scylla-problem
+/operating-scylla/procedures/backup: /operating-scylla/procedures/backup-restore/backup
+/operating-scylla/procedures/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+/operating-scylla/procedures/restore: /operating-scylla/procedures/backup-restore/restore
+/operating-scylla/procedures/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+/operating-scylla/procedures/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+/operating-scylla/procedures/clear_data: /operating-scylla/procedures/cluster-management/clear-data
+/operating-scylla/procedures/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+/operating-scylla/procedures/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+/operating-scylla/procedures/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+/operating-scylla/procedures/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+/operating-scylla/procedures/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+/operating-scylla/procedures/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+/operating-scylla/procedures/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+/operating-scylla/procedures/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+/operating-scylla/procedures/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+/operating-scylla/procedures/revoke_decommission: /operating-scylla/procedures/cluster-management/revoke-decommission
+/operating-scylla/procedures/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+/operating-scylla/procedures/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+/operating-scylla/procedures/repair: /operating-scylla/procedures/maintenance/repair
+/operating-scylla/procedures/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+
+# sstable2
+
+/architecture/sstable/sstable-summary-file: /architecture/sstable/sstable2/sstable-summary-file
+/architecture/sstable/sstable-compression: /architecture/sstable/sstable2/sstable-compression
+/architecture/sstable/sstable-format: /architecture/sstable/sstable2/sstable_format
+/architecture/sstable/sstable-interpretation: /architecture/sstable/sstable2/sstable-interpretation
+/architecture/sstable/sstable-data-file: /architecture/sstable/sstable2/sstable-data-file
+
+# upgrade 2017 - 2018
+/upgrade/upgrade-guide-from-2017.1-to-2018.1: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1
+/upgrade/metric-update-2017.1-to-2018.1: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/metric-update-2017.1-to-2018.1
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-debian
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-rpm
+/upgrade/upgrade-guide-from-2017.1-to-2018.1-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.1-to-2018.1/upgrade-guide-from-2017.1-to-2018.1-ubuntu
+
+# upgrade 2017 - 2017
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-debian
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-rpm
+/upgrade/upgrade-guide-from-2017.x.y-to-2017.x.z-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2017.x.y-to-2017.x.z/upgrade-guide-from-2017.x.y-to-2017.x.z-ubuntu
+
+# upgrade 2018 - 2018
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-rpm: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-rpm
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-ubuntu: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-ubuntu
+/upgrade/upgrade-guide-from-2018.x.y-to-2018.x.z-debian: /upgrade/upgrade-enterprise/upgrade-guide-from-2018.x.y-to-2018.x.z/upgrade-guide-from-2018.x.y-to-2018.x.z-debian
+
+# upgrade manager
+/upgrade/upgrade-guide-from-manager: /upgrade/upgrade-manager/upgrade-guide-from-manager
+/upgrade/upgrade-guide-from-manager-1.0.x-to-1.1.x: /upgrade/upgrade-manager/upgrade-guide-from-manager-1.0.x-to-1.1.x
+/upgrade/upgrade-guide-from-manager-1.1.x-to-1.2.x: /upgrade/upgrade-manager/upgrade-guide-from-manager-1.1.x-to-1.2.x
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-from-2.0.0-to-2.0.1: /upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-from-2.x.y-to-2.x.z
+
+# upgrade monitoring
+/upgrade/upgrade-guide-from-monitoring: /upgrade/upgrade-monitor/upgrade-guide-from-monitoring
+/upgrade/upgrade-guide-from-monitoring-1.x-to-monitoring-2.x: /upgrade/upgrade-monitor/upgrade-guide-from-monitoring-1.x-to-monitoring-2.x
+
+# upgrade OpenSource
+# upgrade 1.0 to 1.1
+/upgrade/upgrade-guide-from-1.0-to-1.1: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1
+/upgrade/upgrade-guide-from-1.0-to-1.1-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1/upgrade-guide-from-1.0-to-1.1-rpm
+/upgrade/upgrade-guide-from-1.0-to-1.1-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.0-to-1.1/upgrade-guide-from-1.0-to-1.1-ubuntu
+
+# upgrade 1.1 to 1.2
+/upgrade/upgrade-guide-from-1.1-to-1.2: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2
+/upgrade/upgrade-guide-from-1.1-to-1.2-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2/upgrade-guide-from-1.1-to-1.2-rpm
+/upgrade/upgrade-guide-from-1.1-to-1.2-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.1-to-1.2/upgrade-guide-from-1.1-to-1.2-ubuntu
+
+# upgrade 1.2 to 1.3
+/upgrade/upgrade-guide-from-1.2-to-1.3: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3
+/upgrade/upgrade-guide-from-1.2-to-1.3-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3/upgrade-guide-from-1.2-to-1.3-rpm
+/upgrade/upgrade-guide-from-1.2-to-1.3-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.2-to-1.3/upgrade-guide-from-1.2-to-1.3-ubuntu
+
+# upgrade 1.3 to 1.4
+
+/upgrade/upgrade-guide-from-1.3-to-1.4: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4
+/upgrade/upgrade-guide-from-1.3-to-1.4-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4/upgrade-guide-from-1.3-to-1.4-rpm
+/upgrade/upgrade-guide-from-1.3-to-1.4-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.3-to-1.4/upgrade-guide-from-1.3-to-1.4-ubuntu
+
+# upgrade 1.4 to 1.5
+/upgrade/upgrade-guide-from-1.4-to-1.5: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5
+/upgrade/upgrade-guide-from-1.4-to-1.5-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5/upgrade-guide-from-1.4-to-1.5-rpm
+/upgrade/upgrade-guide-from-1.4-to-1.5-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.4-to-1.5/upgrade-guide-from-1.4-to-1.5-ubuntu
+
+# upgrade 1.5 to 1.6
+/upgrade/upgrade-guide-from-1.5-to-1.6: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6
+/upgrade/upgrade-guide-from-1.5-to-1.6-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6/upgrade-guide-from-1.5-to-1.6-rpm
+/upgrade/upgrade-guide-from-1.5-to-1.6-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.5-to-1.6/upgrade-guide-from-1.5-to-1.6-ubuntu
+
+# upgrade 1.6 to 1.7
+/upgrade/upgrade-guide-from-1.6-to-1.7: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7
+/upgrade/upgrade-guide-from-1.6-to-1.7-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-rpm
+/upgrade/upgrade-guide-from-1.6-to-1.7-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-ubuntu
+/upgrade/upgrade-guide-from-1.6-to-1.7-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.6-to-1.7/upgrade-guide-from-1.6-to-1.7-debian
+
+# upgrade 1.7 to 2.0
+/upgrade/upgrade-guide-from-1.7-to-2.0: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0
+/upgrade/upgrade-guide-from-1.7-to-2.0-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-rpm
+/upgrade/upgrade-guide-from-1.7-to-2.0-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-ubuntu
+/upgrade/upgrade-guide-from-1.7-to-2.0-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/upgrade-guide-from-1.7-to-2.0-debian
+/upgrade/metric-update-1.7-to-2.0: /upgrade/upgrade-opensource/upgrade-guide-from-1.7-to-2.0/metric-update-1.7-to-2.0
+
+
+# upgrade 1.x.y-to-1.x.z
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-rpm
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-ubuntu
+/upgrade/upgrade-guide-from-1.x.y-to-1.x.z-debian: /upgrade/upgrade-opensource/upgrade-guide-from-1.x.y-to-1.x.z/upgrade-guide-from-1.x.y-to-1.x.z-debian
+
+# upgrade 2.0 to 2.1
+/upgrade/upgrade-guide-from-2.0-to-2.1: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1
+/upgrade/upgrade-guide-from-2.0-to-2.1-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-rpm
+/upgrade/upgrade-guide-from-2.0-to-2.1-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-ubuntu
+/upgrade/upgrade-guide-from-2.0-to-2.1-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/upgrade-guide-from-2.0-to-2.1-debian
+/upgrade/metric-update-2.0-to-2.1: /upgrade/upgrade-opensource/upgrade-guide-from-2.0-to-2.1/metric-update-2.0-to-2.1
+
+# upgrade 2.1 to 2.2
+/upgrade/upgrade-guide-from-2.1-to-2.2: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2
+/upgrade/upgrade-guide-from-2.1-to-2.2-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-rpm
+/upgrade/upgrade-guide-from-2.1-to-2.2-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-ubuntu
+/upgrade/upgrade-guide-from-2.1-to-2.2-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/upgrade-guide-from-2.1-to-2.2-debian
+/upgrade/metric-update-2.1-to-2.2: /upgrade/upgrade-opensource/upgrade-guide-from-2.1-to-2.2/metric-update-2.1-to-2.2
+
+# upgrade 2.2 to 2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-rpm
+/upgrade/upgrade-guide-from-2.2-to-2.3-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-ubuntu
+/upgrade/upgrade-guide-from-2.2-to-2.3-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-debian
+/upgrade/metric-update-2.2-to-2.3: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/metric-update-2.2-to-2.3
+/upgrade/upgrade-guide-from-2.2-to-2.3-ubuntu-16-04: /upgrade/upgrade-opensource/upgrade-guide-from-2.2-to-2.3/upgrade-guide-from-2.2-to-2.3-ubuntu-16-04
+
+# upgrade 2.x.y to 2.x.z
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-debian: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-debian
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-rpm: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-rpm
+/upgrade/upgrade-guide-from-2.x.y-to-2.x.z-ubuntu: /upgrade/upgrade-opensource/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-guide-from-2.x.y-to-2.x.z-ubuntu
+
+# Upgrade OS to Enterprise
+/upgrade/upgrade-guide-from-1.6-to-2017.1: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1
+/upgrade/upgrade-guide-from-1.6-to-2017.1-debian: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-debian
+/upgrade/upgrade-guide-from-1.6-to-2017.1-rpm: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-rpm
+/upgrade/upgrade-guide-from-1.6-to-2017.1-ubuntu: /upgrade/upgrade-to-enterprise/upgrade-guide-from-1.6-to-2017.1/upgrade-guide-from-1.6-to-2017.1-ubuntu
+
+/upgrade/upgrade-guide-from-2.0-to-2018.1: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1
+/upgrade/upgrade-guide-from-2.0-to-2018.1-debian: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2087.1/upgrade-guide-from-2.0-to-2018.1-debian
+/upgrade/upgrade-guide-from-2.0-to-2018.1-rpm: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1/upgrade-guide-from-2.0-to-2018.1-rpm
+/upgrade/upgrade-guide-from-2.0-to-2018.1-ubuntu: /upgrade/upgrade-to-enterprise/upgrade-guide-from-2.0-to-2018.1/upgrade-guide-from-2.0-to-2018.1-ubuntu
+
+/operating-scylla/upgrade: /upgrade
+/rst_include/upgrade-index: /upgrade
+
+#removed page - how to kb
+/kb/kb-howto: /kb
+
+# monitoring
+/operating-scylla/monitoring/Scylla_Monitoring_Cheatsheet.pdf: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitor_troubleshoot: /operating-scylla/monitoring
+/operating-scylla/monitoring/min-prod-hw: /operating-scylla/monitoring
+/operating-scylla/monitoring/cql_optimization: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitoring_apis: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitor_without_docker.2.1: /operating-scylla/monitoring
+/operating-scylla/monitoring/updating_dashboard: /operating-scylla/monitoring
+/operating-scylla/monitoring/_common/monitor-back-index: /operating-scylla/monitoring
+/operating-scylla/monitoring/monitoring_stack: /operating-scylla/monitoring
+
+#scylla-learn
+/using-scylla/learn-example: /using-scylla/learn
+
+# scylla-matrix
+/getting-started/support-matrix: /getting-started
+
+# operators
+/getting-started/cql/operators: /getting-started/cql
+
+# move kb for Kafka connector to Integrations
+/kb/kafka-connector: /using-scylla/integrations/kafka-connector
+/kb/sink-config: /using-scylla/integrations/sink-config
+
+# rename repair file in manager issue #2387
+/operating-scylla/manager/2.0/repair-a-cluster: /operating-scylla/manager
+
+# https://github.com/scylladb/scylla-docs/issues/2412
+/operating-scylla/runtime-authentication: /operating-scylla/security/runtime-authentication
+
+# https://github.com/scylladb/scylla-doc-issues/issues/298
+/kb/os-support: /getting-started/os-support
+
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z: /upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-2.x.y-to-2.x.z: /upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-2.x.a-to-2.y.b
+/upgrade/upgrade-manager/upgrade-guide-from-2.x.y-to-2.x.z/upgrade-row-level-repair: /upgrade/upgrade-manager/upgrade-2.x.a-to-2.y.b/upgrade-row-level-repair
+
+# scylla-cloud rename BYOA
+/scylla-cloud/cloud-setup/xaws-account: /scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa
+
+# scylla Monitor
+/operating-scylla/monitoring/matrix: https://monitoring.docs.scylladb.com/stable/reference/matrix.html
+
+#scylla operator
+/operating-scylla/scylla-operator/generic: https://scylladb.github.io/scylla-operator/master/generic
+/operating-scylla/scylla-operator/eks: https://scylladb.github.io/scylla-operator/master/eks
+/operating-scylla/scylla-operator/gke: https://scylladb.github.io/scylla-operator/master/gke
+/operating-scylla/scylla-operator/manager: https://scylladb.github.io/scylla-operator/master/manager
+/operating-scylla/scylla-operator/scylla_cluster_crd: https://scylladb.github.io/scylla-operator/master/scylla_cluster_crd
+/operating-scylla/scylla-operator/contributing: https://scylladb.github.io/scylla-operator/master/contributing
+
+#scylla-manager
+/operating-scylla/manager/2.2: https://manager.docs.scylladb.com/branch-2.2/index.html
+/operating-scylla/manager/2.2/backup: https://manager.docs.scylladb.com/branch-2.2/backup
+/operating-scylla/manager/2.2/backup/backup-examples: https://manager.docs.scylladb.com/branch-2.2/backup/examples
+/operating-scylla/manager/2.2/backup/get-schema: https://manager.docs.scylladb.com/branch-2.2/backup
+/operating-scylla/manager/2.2/backup/grant-access-S3: https://manager.docs.scylladb.com/branch-2.2/backup/setup-aws-s3
+/operating-scylla/manager/2.2/backup/grant-access-gcs: https://manager.docs.scylladb.com/branch-2.2/backup/setup-gcs
+/operating-scylla/manager/2.2/cluster-health-check: https://manager.docs.scylladb.com/branch-2.2/health-check.rst
+/operating-scylla/manager/2.2/config/index: https://manager.docs.scylladb.com/branch-2.2/config/index
+/operating-scylla/manager/2.2/config/scylla-manager-agent-config: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-agent-config
+/operating-scylla/manager/2.2/config/scylla-manager-agent: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-agent-config
+/operating-scylla/manager/2.2/config/scylla-manager-config: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-config
+/operating-scylla/manager/2.2/config/scylla-manager: https://manager.docs.scylladb.com/branch-2.2/config/scylla-manager-config
+/operating-scylla/manager/2.2/index: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/introduction-to-scylla-manager: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/manage-nodes/add-a-cluster: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/add-node: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/connect-cluster-to-monitor: https://manager.docs.scylladb.com/branch-2.2/add-a-cluster
+/operating-scylla/manager/2.2/manage-nodes/index: https://manager.docs.scylladb.com/branch-2.2/index
+/operating-scylla/manager/2.2/manage-nodes/remove-node: https://manager.docs.scylladb.com/branch-2.2/troubleshooting
+/operating-scylla/manager/2.2/sctool/backup: https://manager.docs.scylladb.com/branch-2.2/sctool/backup
+/operating-scylla/manager/2.2/sctool/cluster: https://manager.docs.scylladb.com/branch-2.2/sctool/cluster
+/operating-scylla/manager/2.2/sctool/global-flags-and-variables: https://manager.docs.scylladb.com/branch-2.2/sctool/global-flags-and-variables
+/operating-scylla/manager/2.2/sctool/index: https://manager.docs.scylladb.com/branch-2.2/sctool/index
+/operating-scylla/manager/2.2/sctool/repair: https://manager.docs.scylladb.com/branch-2.2/repair/index
+/operating-scylla/manager/2.2/sctool/status: https://manager.docs.scylladb.com/branch-2.2/status
+/operating-scylla/manager/2.2/sctool/task: https://manager.docs.scylladb.com/branch-2.2/sctool/task
+/operating-scylla/manager/2.2/sctool/version: https://manager.docs.scylladb.com/branch-2.2/sctool/version
+/operating-scylla/manager/2.2/scylla-manager-agent-installation: https://manager.docs.scylladb.com/branch-2.2/install-scylla-manager-agent
+/operating-scylla/manager/2.2/scylla-manager-installation: https://manager.docs.scylladb.com/branch-2.2/install-scylla-manager
+/operating-scylla/manager/2.2/scylla-monitoring-integration: https://manager.docs.scylladb.com/branch-2.2/scylla-monitoring
+/operating-scylla/manager/2.2/backup/prepare-nodes: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/backup/index: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/backup/restore-a-backup: https://manager.docs.scylladb.com/branch-2.2/backup/index
+/operating-scylla/manager/2.2/repair-a-cluster: https://manager.docs.scylladb.com/branch-2.2/repair/index
+
+# Remove Scylla Alternator and move to OSS docs site
+
+/using-scylla/alternator/alternator: https://scylladb.github.io/scylla/stable/alternator/alternator
+/using-scylla/alternator/getting-started: https://scylladb.github.io/scylla/stable/alternator/getting-started
+
+# Create Drivers directory and move files to it
+/getting-started/scylla_drivers: /using-scylla/drivers/cql-drivers/index
+/using-scylla/drivers-intro: /using-scylla/drivers/cql-drivers/index
+/using-scylla/scylla-cpp-driver: /using-scylla/drivers/cql-drivers/scylla-cpp-driver
+/using-scylla/scylla-go-driver: /using-scylla/drivers/cql-drivers/scylla-go-driver
+/using-scylla/scylla-gocqlx-driver: /using-scylla/drivers/cql-drivers/scylla-gocqlx-driver
+/using-scylla/scylla-java-driver: /using-scylla/drivers/cql-drivers/scylla-java-driver
+/using-scylla/scylla-python-driver: /using-scylla/drivers/cql-drivers/scylla-python-driver
+/using-scylla/scylla_drivers: /using-scylla/drivers
+
+# change vpc peering to AWS vpc peering
+/scylla-cloud/cloud-setup/vpc-peering: /scylla-cloud/cloud-setup/AWS/aws-vpc-peering
+
+#remove social reader KB
+/kb/social-reader: /kb/index
+
+# move scylla cloud for AWS to dedicated directory
+/scylla-cloud/cloud-setup/aws-vpc-peering: /scylla-cloud/cloud-setup/AWS/aws-vpc-peering
+/scylla-cloud/cloud-setup/cloud-prom-proxy: /scylla-cloud/cloud-setup/AWS/cloud-prom-proxy
+/scylla-cloud/cloud-setup/outposts: /scylla-cloud/cloud-setup/AWS/outposts
+/scylla-cloud/cloud-setup/scylla-cloud-byoa: /scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa
+
+# Scylla Cloud
+/scylla-cloud/cloud-setup/gcp-vpc-peering: /scylla-cloud/cloud-setup/GCP/gcp-vpc-peering
+/scylla-cloud/cloud-setup/GCP/gcp-vcp-peering: /scylla-cloud/cloud-setup/GCP/gcp-vpc-peering
+
+# replace underscore with dash for install_scylla
+/getting-started/install_scylla/air-gapped-install: /getting-started/install-scylla/air-gapped-install
+/getting-started/install_scylla/config-commands: /getting-started/install-scylla/config-commands
+/getting-started/install_scylla/dev_mod: /getting-started/install-scylla/dev-mod
+/getting-started/install_scylla/disable_housekeeping: /getting-started/install-scylla/disable-housekeeping
+/getting-started/install_scylla/index: /getting-started/install-scylla/index
+/getting-started/install_scylla/rpm_info: /getting-started/install-scylla/rpm-info
+/getting-started/install_scylla/unified-installer: /getting-started/install-scylla/unified-installer
+
+# replace underscore with dash for error_messages
+/troubleshooting/error_messages/address_already_in_use: /troubleshooting/error-messages/address-already-in-use
+/troubleshooting/error_messages/create_mv: /troubleshooting/error-messages/create-mv
+/troubleshooting/error_messages/index: /troubleshooting/error-messages/index
+/troubleshooting/error_messages/invalid-ssl-prot-error: /troubleshooting/error-messages/invalid-ssl-prot-error
+/troubleshooting/error_messages/kb_fs_not_qualified_aio: /troubleshooting/error-messages/kb-fs-not-qualified-aio
+/troubleshooting/error_messages/schema_mismatch: /troubleshooting/error-messages/schema-mismatch
+
+
+# replace underscore with dash for files names
+/troubleshooting/large_rows_large_cells_tables: /troubleshooting/large-rows-large-cells-tables
+/troubleshooting/pointless_compactions: /troubleshooting/pointless-compactions
+/troubleshooting/debugging_large_partition: /troubleshooting/debugging-large-partition
+/troubleshooting/large_partition_table: /troubleshooting/large-partition-table
+/troubleshooting/copy_from_failed: /troubleshooting/copy-from-failed
+/troubleshooting/password_reset: /troubleshooting/password-reset
+/troubleshooting/reverse_dns_sshd: /troubleshooting/reverse-dns-sshd
+/troubleshooting/failed_decommission: /troubleshooting/failed-decommission
+/troubleshooting/drop_table_space_up: /troubleshooting/drop-table-space-up
+/troubleshooting/error-messages/create_mv: /troubleshooting/error-messages/create-mv
+/troubleshooting/error-messages/kb_fs_not_qualified_aio: /troubleshooting/error-messages/kb-fs-not-qualified-aio
+/troubleshooting/error-messages/address_already_in_use: /troubleshooting/error-messages/address-already-in-use
+/troubleshooting/error-messages/schema_mismatch: /troubleshooting/error-messages/schema-mismatch
+/troubleshooting/scylla_wont_start: /troubleshooting/scylla-wont-start
+/troubleshooting/change_ownership: /troubleshooting/change-ownership
+/troubleshooting/space_up: /troubleshooting/space-up
+/troubleshooting/report_scylla_problem: /troubleshooting/report-scylla-problem
+/troubleshooting/sstable_corruption: /troubleshooting/sstable-corruption
+/troubleshooting/log_level: /troubleshooting/log-level
+/troubleshooting/manager_monitoring_integration: /troubleshooting/manager-monitoring-integration
+/getting-started/non-reserved_keywords: /getting-started/non-reserved-keywords
+/getting-started/install-scylla/rpm_info: /getting-started/install-scylla/rpm-info
+/getting-started/install-scylla/dev_mod: /getting-started/install-scylla/dev-mod
+/getting-started/install-scylla/disable_housekeeping: /getting-started/install-scylla/disable-housekeeping
+/getting-started/time_to_live: /getting-started/time-to-live
+/getting-started/secondary_indexes: /getting-started/secondary-indexes
+/getting-started/scylla_in_a_shared_environment: /getting-started/scylla-in-a-shared-environment
+/getting-started/reserved_keywords: /getting-started/reserved-keywords
+/using-scylla/integrations/integration_kairos: /using-scylla/integrations/integration-kairos
+/upgrade/ami_upgrade: /upgrade/ami-upgrade
+/scylla-cloud/cloud-services/scylla_cloud_costs: /scylla-cloud/cloud-services/scylla-cloud-costs
+/scylla-cloud/cloud-services/scylla_cloud_managin_versions: /scylla-cloud/cloud-services/scylla-cloud-managin-versions
+/scylla-cloud/cloud-services/scylla_cloud_support_alerts_sla: /scylla-cloud/cloud-services/scylla-cloud-support-alerts-sla
+/scylla-cloud/cloud-services/scylla_cloud-autoscale-and-resizing: /scylla-cloud/cloud-services/scylla-cloud-autoscale-and-resizing
+/operating-scylla/monitoring/3.1/monitoring_stack: /operating-scylla/monitoring/3.1/monitoring-stack
+/operating-scylla/monitoring/3.1/updating_dashboard: /operating-scylla/monitoring/3.1/updating-dashboard
+/operating-scylla/monitoring/3.1/cql_optimization: /operating-scylla/monitoring/3.1/cql-optimization
+/operating-scylla/monitoring/3.1/monitoring_apis: /operating-scylla/monitoring/3.1/monitoring-apis
+/operating-scylla/monitoring/3.1/monitor_troubleshoot: /operating-scylla/monitoring/3.1/monitor-troubleshoot
+/operating-scylla/monitoring/3.1/monitor: t_docker with ./operating-scylla/monitoring/3.1/monitor-without-docker
+/operating-scylla/monitoring/2.4/monitoring_stack: /operating-scylla/monitoring/2.4/monitoring-stack
+/operating-scylla/monitoring/2.4/updating_dashboard: /operating-scylla/monitoring/2.4/updating-dashboard
+/operating-scylla/monitoring/2.4/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.4/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.4/cql_optimization: /operating-scylla/monitoring/2.4/cql-optimization
+/operating-scylla/monitoring/2.4/monitoring_apis: /operating-scylla/monitoring/2.4/monitoring-apis
+/operating-scylla/monitoring/2.4/monitor_troubleshoot: /operating-scylla/monitoring/2.4/monitor-troubleshoot
+/operating-scylla/monitoring/2.2/monitoring_stack: /operating-scylla/monitoring/2.2/monitoring-stack
+/operating-scylla/monitoring/2.2/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.2/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.2/monitoring_apis: /operating-scylla/monitoring/2.2/monitoring-apis
+/operating-scylla/monitoring/2.2/monitor_troubleshoot: /operating-scylla/monitoring/2.2/monitor-troubleshoot
+/operating-scylla/monitoring/3.4/monitoring_stack: /operating-scylla/monitoring/3.4/monitoring-stack
+/operating-scylla/monitoring/3.4/start_all: /operating-scylla/monitoring/3.4/start-all
+/operating-scylla/monitoring/3.4/updating_dashboard: /operating-scylla/monitoring/3.4/updating-dashboard
+/operating-scylla/monitoring/3.4/cql_optimization: /operating-scylla/monitoring/3.4/cql-optimization
+/operating-scylla/monitoring/3.4/monitoring_apis: /operating-scylla/monitoring/3.4/monitoring-apis
+/operating-scylla/monitoring/3.4/monitor_troubleshoot: /operating-scylla/monitoring/3.4/monitor-troubleshoot
+/operating-scylla/monitoring/3.4/monitor: t_docker with ./operating-scylla/monitoring/3.4/monitor-without-docker
+/operating-scylla/monitoring/3.3/monitoring_stack: /operating-scylla/monitoring/3.3/monitoring-stack
+/operating-scylla/monitoring/3.3/start_all: /operating-scylla/monitoring/3.3/start-all
+/operating-scylla/monitoring/3.3/updating_dashboard: /operating-scylla/monitoring/3.3/updating-dashboard
+/operating-scylla/monitoring/3.3/cql_optimization: /operating-scylla/monitoring/3.3/cql-optimization
+/operating-scylla/monitoring/3.3/monitoring_apis: /operating-scylla/monitoring/3.3/monitoring-apis
+/operating-scylla/monitoring/3.3/monitor_troubleshoot: /operating-scylla/monitoring/3.3/monitor-troubleshoot
+/operating-scylla/monitoring/3.3/monitor: t_docker with ./operating-scylla/monitoring/3.3/monitor-without-docker
+/operating-scylla/monitoring/3.2/monitoring_stack: /operating-scylla/monitoring/3.2/monitoring-stack
+/operating-scylla/monitoring/3.2/start_all: /operating-scylla/monitoring/3.2/start-all
+/operating-scylla/monitoring/3.2/updating_dashboard: /operating-scylla/monitoring/3.2/updating-dashboard
+/operating-scylla/monitoring/3.2/cql_optimization: /operating-scylla/monitoring/3.2/cql-optimization
+/operating-scylla/monitoring/3.2/monitoring_apis: /operating-scylla/monitoring/3.2/monitoring-apis
+/operating-scylla/monitoring/3.2/monitor_troubleshoot: /operating-scylla/monitoring/3.2/monitor-troubleshoot
+/operating-scylla/monitoring/3.2/monitor: t_docker with ./operating-scylla/monitoring/3.2/monitor-without-docker
+/operating-scylla/monitoring/3.0/monitoring_stack: /operating-scylla/monitoring/3.0/monitoring-stack
+/operating-scylla/monitoring/3.0/updating_dashboard: /operating-scylla/monitoring/3.0/updating-dashboard
+/operating-scylla/monitoring/3.0/cql_optimization: /operating-scylla/monitoring/3.0/cql-optimization
+/operating-scylla/monitoring/3.0/monitoring_apis: /operating-scylla/monitoring/3.0/monitoring-apis
+/operating-scylla/monitoring/3.0/monitor_troubleshoot: /operating-scylla/monitoring/3.0/monitor-troubleshoot
+/operating-scylla/monitoring/3.0/monitor: t_docker with ./operating-scylla/monitoring/3.0/monitor-without-docker
+/operating-scylla/monitoring/2.3/monitoring_stack: /operating-scylla/monitoring/2.3/monitoring-stack
+/operating-scylla/monitoring/2.3/updating_dashboard: /operating-scylla/monitoring/2.3/updating-dashboard
+/operating-scylla/monitoring/2.3/monitor: t_docker.2.1 with ./operating-scylla/monitoring/2.3/monitor-without-docker.2.1
+/operating-scylla/monitoring/2.3/cql_optimization: /operating-scylla/monitoring/2.3/cql-optimization
+/operating-scylla/monitoring/2.3/monitoring_apis: /operating-scylla/monitoring/2.3/monitoring-apis
+/operating-scylla/monitoring/2.3/monitor_troubleshoot: /operating-scylla/monitoring/2.3/monitor-troubleshoot
+/operating-scylla/procedures/config-change/switch_snitch: /operating-scylla/procedures/config-change/switch-snitch
+/operating-scylla/procedures/config-change/change_compaction: /operating-scylla/procedures/config-change/change-compaction
+/operating-scylla/procedures/config-change/rolling_restart: /operating-scylla/procedures/config-change/rolling-restart
+/operating-scylla/procedures/cassandra_to_scylla_migration_process: /operating-scylla/procedures/cassandra-to-scylla-migration-process
+/operating-scylla/procedures/backup-restore/delete_snapshot: /operating-scylla/procedures/backup-restore/delete-snapshot
+/operating-scylla/procedures/tips/best_practices_scylla_on_docker: /operating-scylla/procedures/tips/best-practices-scylla-on-docker
+/operating-scylla/procedures/cluster-management/replace_running_node: /operating-scylla/procedures/cluster-management/replace-running-node
+/operating-scylla/procedures/cluster-management/create_cluster_multidc: /operating-scylla/procedures/cluster-management/create-cluster-multidc
+/operating-scylla/procedures/cluster-management/clear_data: /operating-scylla/procedures/cluster-management/clear-data
+/operating-scylla/procedures/cluster-management/replace_dead_node_or_more: /operating-scylla/procedures/cluster-management/replace-dead-node-or-more
+/operating-scylla/procedures/cluster-management/remove_seed: /operating-scylla/procedures/cluster-management/remove-seed
+/operating-scylla/procedures/cluster-management/add_node_to_cluster: /operating-scylla/procedures/cluster-management/add-node-to-cluster
+/operating-scylla/procedures/cluster-management/membership_changes: /operating-scylla/procedures/cluster-management/membership-changes
+/operating-scylla/procedures/cluster-management/replace_seed_node: /operating-scylla/procedures/cluster-management/replace-seed-node
+/operating-scylla/procedures/cluster-management/ec2_dc: /operating-scylla/procedures/cluster-management/ec2-dc
+/operating-scylla/procedures/cluster-management/add_dc_to_existing_dc: /operating-scylla/procedures/cluster-management/add-dc-to-existing-dc
+/operating-scylla/procedures/cluster-management/remove_node: /operating-scylla/procedures/cluster-management/remove-node
+/operating-scylla/procedures/cluster-management/replace_dead_node: /operating-scylla/procedures/cluster-management/replace-dead-node
+/operating-scylla/procedures/cluster-management/revoke_decommission: /operating-scylla/procedures/cluster-management/revoke-decommission
+/operating-scylla/procedures/cluster-management/create_cluster: /operating-scylla/procedures/cluster-management/create-cluster
+/operating-scylla/procedures/cluster-management/decommissioning_data_center: /operating-scylla/procedures/cluster-management/decommissioning-data-center
+/operating-scylla/security/security_checklist: /operating-scylla/security/security-checklist
+/operating-scylla/security/client_node_encryption: /operating-scylla/security/client-node-encryption
+/operating-scylla/security/generate_certificate: /operating-scylla/security/generate-certificate
+/operating-scylla/security/node_node_encryption: /operating-scylla/security/node-node-encryption
+/operating-scylla/security/rbac_usecase: /operating-scylla/security/rbac-usecase
+/architecture/console_CL_full_demo: /architecture/console-CL-full-demo
+/architecture/sstable/sstable3/sstables_3_statistics: /architecture/sstable/sstable3/sstables-3-statistics
+/architecture/sstable/sstable3/sstables_3_summary: /architecture/sstable/sstable3/sstables-3-summary
+/architecture/sstable/sstable3/sstables_3_data_file_format: /architecture/sstable/sstable3/sstables-3-data-file-format
+/architecture/sstable/sstable3/sstables_3_index: /architecture/sstable/sstable3/sstables-3-index
+/architecture/sstable/sstable3/sstable_format: /architecture/sstable/sstable3/sstable-format
+
+
+# scylla-cloud migration
+/scylla-cloud: https://cloud.docs.scylladb.com/stable/
+
+/scylla-cloud/cloud-services: https://cloud.docs.scylladb.com/stable/cloud-services
+/scylla-cloud/cloud-services/cloud-backup: https://cloud.docs.scylladb.com/stable/cloud-services/cloud-backup
+/scylla-cloud/cloud-services/scylla-cloud-autoscale-and-resizing: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-autoscale-and-resizing
+/scylla-cloud/cloud-services/scylla-cloud-costs: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-costs
+/scylla-cloud/cloud-services/scylla-cloud-deployment-locations: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-deployment-locations
+/scylla-cloud/cloud-services/scylla-cloud-managin-versions: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-managin-versions
+/scylla-cloud/cloud-services/scylla-cloud-support-alerts-sla: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-support-alerts-sla
+/scylla-cloud/cloud-services/scylla-cloud-value: https://cloud.docs.scylladb.com/stable/cloud-services/scylla-cloud-value
+
+/scylla-cloud/cloud-setup/AWS: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS
+/scylla-cloud/cloud-setup/AWS/aws-vpc-peering: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/aws-vpc-peering
+/scylla-cloud/cloud-setup/AWS/cloud-prom-proxy: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/cloud-prom-proxy
+/scylla-cloud/cloud-setup/AWS/outposts: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/outposts
+/scylla-cloud/cloud-setup/AWS/scylla-cloud-byoa: https://cloud.docs.scylladb.com/stable/cloud-setup/AWS/scylla-cloud-byoa
+/scylla-cloud/cloud-setup/GCP: https://cloud.docs.scylladb.com/stable/cloud-setup/GCP
+/scylla-cloud/cloud-setup/GCP/gcp-vpc-peering: https://cloud.docs.scylladb.com/stable/cloud-setup/GCP/gcp-vpc-peering
+/scylla-cloud/cloud-setup/FAQ: https://cloud.docs.scylladb.com/stable/cloud-setup/FAQ
+/scylla-cloud/cloud-setup/scylla-best-practices: https://cloud.docs.scylladb.com/stable/cloud-setup/scylla-best-practices
+
+
+/scylla-cloud/learn-more: https://cloud.docs.scylladb.com/stable/learn-more
+
+/scylla-cloud/security: https://cloud.docs.scylladb.com/stable/security
+/scylla-cloud/security/best_practices: https://cloud.docs.scylladb.com/stable/security/best_practices
+/scylla-cloud/security/concepts: https://cloud.docs.scylladb.com/stable/security/concepts
+
diff --git a/docs/_utils/remove-redirection-loops.py b/docs/_utils/remove-redirection-loops.py
--- a/docs/_utils/remove-redirection-loops.py
+++ b/docs/_utils/remove-redirection-loops.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+# update redirection file to remove double redireaction
+# a->b, b->c, is rewritten ad a->c,b->c
+# write result to stdout
+
+import os
+import sys
+import re
+import yaml
+
+f = './redirections.yaml'
+new_f = './redirections.new.yaml'
+d = yaml.load(open(f), Loader=yaml.FullLoader)
+replace_dict = {}
+for key, value in d.items():
+ if value in d.keys():
+# print ("duble redirection:", key, "->", value, "->", d[value])
+ replace_dict[value] = d[value]
+
+with open(f, "r") as source:
+ lines = source.readlines()
+ for line in lines:
+ dline = yaml.safe_load(line)
+ if (dline is not None):
+ for key, value in dline.items():
+ if value in replace_dict.keys():
+ print (key, ": ", replace_dict[value],sep="")
+ else:
+ print(line, end='')
+ else:
+ print(line, end='')
+
diff --git a/docs/architecture/1-write_op_RF_3.jpg b/docs/architecture/1-write_op_RF_3.jpg
--- a/docs/architecture/1-write_op_RF_3.jpg
+++ b/docs/architecture/1-write_op_RF_3.jpg
null
diff --git a/docs/architecture/2-read_op_RF_3.jpg b/docs/architecture/2-read_op_RF_3.jpg
--- a/docs/architecture/2-read_op_RF_3.jpg
+++ b/docs/architecture/2-read_op_RF_3.jpg
null
diff --git a/docs/architecture/3-write_op_RF_3_CL_1.jpg b/docs/architecture/3-write_op_RF_3_CL_1.jpg
--- a/docs/architecture/3-write_op_RF_3_CL_1.jpg
+++ b/docs/architecture/3-write_op_RF_3_CL_1.jpg
null
diff --git a/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg b/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
--- a/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
+++ b/docs/architecture/4-write_op_RF_3_CL_Quorum.jpg
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_1.jpg b/docs/architecture/5-read_op_RF_3_CL_1.jpg
--- a/docs/architecture/5-read_op_RF_3_CL_1.jpg
+++ b/docs/architecture/5-read_op_RF_3_CL_1.jpg
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_1.xcf b/docs/architecture/5-read_op_RF_3_CL_1.xcf
--- a/docs/architecture/5-read_op_RF_3_CL_1.xcf
+++ b/docs/architecture/5-read_op_RF_3_CL_1.xcf
null
diff --git a/docs/architecture/5-read_op_RF_3_CL_2.jpg b/docs/architecture/5-read_op_RF_3_CL_2.jpg
--- a/docs/architecture/5-read_op_RF_3_CL_2.jpg
+++ b/docs/architecture/5-read_op_RF_3_CL_2.jpg
null
diff --git a/docs/architecture/6-CAP_Theorem.jpg b/docs/architecture/6-CAP_Theorem.jpg
--- a/docs/architecture/6-CAP_Theorem.jpg
+++ b/docs/architecture/6-CAP_Theorem.jpg
null
diff --git a/docs/architecture/anti-entropy/1_read_repair.png b/docs/architecture/anti-entropy/1_read_repair.png
--- a/docs/architecture/anti-entropy/1_read_repair.png
+++ b/docs/architecture/anti-entropy/1_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/2_read_repair.png b/docs/architecture/anti-entropy/2_read_repair.png
--- a/docs/architecture/anti-entropy/2_read_repair.png
+++ b/docs/architecture/anti-entropy/2_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/3_read_repair.png b/docs/architecture/anti-entropy/3_read_repair.png
--- a/docs/architecture/anti-entropy/3_read_repair.png
+++ b/docs/architecture/anti-entropy/3_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/4_read_repair.png b/docs/architecture/anti-entropy/4_read_repair.png
--- a/docs/architecture/anti-entropy/4_read_repair.png
+++ b/docs/architecture/anti-entropy/4_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/5_read_repair.png b/docs/architecture/anti-entropy/5_read_repair.png
--- a/docs/architecture/anti-entropy/5_read_repair.png
+++ b/docs/architecture/anti-entropy/5_read_repair.png
null
diff --git a/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png b/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
--- a/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
+++ b/docs/architecture/anti-entropy/6_Read_Path_with_Read_Repair.png
null
diff --git a/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png b/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
--- a/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
+++ b/docs/architecture/anti-entropy/7_Read_Path_with_Probabilistic_Read_Repair.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-3.png b/docs/architecture/anti-entropy/hinted-handoff-3.png
--- a/docs/architecture/anti-entropy/hinted-handoff-3.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-3.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-4.png b/docs/architecture/anti-entropy/hinted-handoff-4.png
--- a/docs/architecture/anti-entropy/hinted-handoff-4.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-4.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff-5.png b/docs/architecture/anti-entropy/hinted-handoff-5.png
--- a/docs/architecture/anti-entropy/hinted-handoff-5.png
+++ b/docs/architecture/anti-entropy/hinted-handoff-5.png
null
diff --git a/docs/architecture/anti-entropy/hinted-handoff.rst b/docs/architecture/anti-entropy/hinted-handoff.rst
--- a/docs/architecture/anti-entropy/hinted-handoff.rst
+++ b/docs/architecture/anti-entropy/hinted-handoff.rst
@@ -0,0 +1,49 @@
+Scylla Hinted Handoff
+=====================
+
+A typical write in Scylla works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.
+
+But what happens when a write request is sent to a Scylla node that is unresponsive due to reasons including heavy write load on a node, network issues, or even hardware failure? To ensure availability and consistency, Scylla implements :term:`hinted handoff<Hinted Handoff>`.
+
+ :term:`Hint<Hint>` = target replica ID + :term:`mutation<Mutation>` data
+
+
+In other words, Scylla saves a copy of the writes intended for down nodes, and replays them to the nodes when they are up later. Thus, the write operation flow, when a node is down, looks like this:
+
+1. The co-ordinator determines all the replica nodes;
+
+2. Based on the replication factor (RF) , the co-ordinator :doc:`attempts to write to RF nodes </architecture/architecture-fault-tolerance>`;
+
+.. image:: ../1-write_op_RF_3.jpg
+
+3. If one node is down, acknowledgments are only returned from two nodes:
+
+.. image:: hinted-handoff-3.png
+
+4. If the consistency level does not require responses from all replicas, the co-ordinator, *V* in this case, will respond to the client that the write was successful. The co-ordinator will write and store a :term:`hint<Hint>` for the missing node:
+
+.. image:: hinted-handoff-4.png
+
+5. Once the down node comes up, the co-ordinator will replay the hint for that node. After the co-ordinator receives an acknowledgement of the write, the hint is deleted.
+
+.. image:: hinted-handoff-5.png
+
+A co-ordinator stores hints for a handoff under the following conditions:
+
+1. For down nodes;
+2. If the replica doesn't respond within :code:`write_request_timeout_in_ms`.
+
+The co-ordinator will stop creating any hints for a dead node if the node's downtime is greater than :code:`max_hint_window_in_ms`.
+
+Hinted handoff is enabled and managed by these settings in :code:`scylla.yaml`:
+
+* :code:`hinted_handoff_enabled`: enables or disables the hinted handoff feature completely or enumerates data centers where hints are allowed. By default, “true” enables hints to all nodes.
+* :code:`max_hint_window_in_ms`: do not generate hints if the destination node has been down for more than this value. If a node is down longer than this period, new hints are not created. Hint generation resumes once the destination node is back up. By default, this is set to 3 hours.
+* :code:`hints_directory`: the directory where Scylla will store hints. By default this is :code:`$SCYLLA_HOME/hints`.
+
+Storing of the hint can also fail. Enabling hinted handoff therefore does not eliminate the need for repair; a user must recurrently :doc:`run a full repair </operating-scylla/procedures/maintenance/repair/>` to ensure data consistency across the cluster nodes.
+
+Hinted handoff was released as production-ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/anti-entropy/index.rst b/docs/architecture/anti-entropy/index.rst
--- a/docs/architecture/anti-entropy/index.rst
+++ b/docs/architecture/anti-entropy/index.rst
@@ -0,0 +1,34 @@
+Scylla Anti-Entropy
+===================
+
+.. toctree::
+ :hidden:
+ :glob:
+
+ Scylla Hinted Handoff <hinted-handoff/>
+ Scylla Read Repair <read-repair/>
+ Scylla Repair </operating-scylla/procedures/maintenance/repair/>
+
+
+Scylla replicates data according to :term:`eventual consistency<Eventual Consistency>`. This means that, in Scylla, when considering the :term:`CAP Theorem<CAP Theorem>`, availability and partition tolerance are considered a higher priority over consistency. Although Scylla’s tunable consistency allows users to make a tradeoff between availability and consistency, Scylla’s :term:`consistency level<Consistency Level (CL)>` is tunable per query.
+
+However, over time, there can be a number of reasons for data inconsistencies, including:
+
+1. a down node;
+2. a network partition;
+3. dropped mutations;
+4. process crashes (before a flush);
+5. a replica that cannot write due to being out of resources;
+6. file corruption.
+
+To mitigate :term:`entropy<Entropy>`, or data inconsistency, Scylla uses a few different processes. The goal of Scylla :term:`anti-entropy<Anti-Entropy>` - based on that of Apache Cassandra - is to compare data on all replicas, synchronize data between all replicas, and, finally, ensure each replica has the most recent data.
+
+Anti-entropy measures include *write-time* changes such as :term:`hinted handoff<Hinted Handoff>`, *read-time* changes such as :term:`read repair<Read Repair>`, and finally, periodic maintenance via :term:`repair<Repair>`.
+
+* :doc:`Scylla Hinted Handoff <hinted-handoff/>` - High-Level view of Scylla Hinted Handoff
+* :doc:`Scylla Read Repair <read-repair/>` - High-Level view of Scylla Read Repair
+* :doc:`Scylla Repair </operating-scylla/procedures/maintenance/repair/>` - Description of Scylla Repair
+
+Also learn more in the `Cluster Management, Repair and Scylla Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/topic/cluster-management-repair-and-scylla-manager/>`_ on Scylla University.
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/anti-entropy/read-repair.rst b/docs/architecture/anti-entropy/read-repair.rst
--- a/docs/architecture/anti-entropy/read-repair.rst
+++ b/docs/architecture/anti-entropy/read-repair.rst
@@ -0,0 +1,83 @@
+Scylla Read Repair
+==================
+
+Read repair serves as an anti-entropy mechanism during read path.
+
+On read operations, Scylla runs a process called :term:`read repair<Read Repair>`, to ensure that replicas are updated with most recently updated data. Such repairs during read path run automatically, asynchronously, and in the background.
+
+Note however, that if digest mismatch is detected before consistency level is reached, that repair will run in the foreground.
+
+A normal read operation works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.
+
+Read Request
+^^^^^^^^^^^^
+This image illustrates the flow of a read request, when data is out of sync, and a background read repair process is triggered.
+
+.. image:: 1_read_repair.png
+
+1. Our coordinator, *V*, **requests data** (including digest) from one node, *W*, which is out of date.
+
+2. The coordinator also **requests digests** from the number of nodes up to the consistency level (in this case, *Quorum* or 2) which, in this case, includes Node *X*.
+
+3. If the digests from all replicas match, the coordinator responds to the client with the read data. If there is a mismatch (shown above), a :term:`read repair<Read Repair>` is performed.
+
+Read Repair
+^^^^^^^^^^^
+See the appendices below for the detailed flow.
+
+1. Triggered by a mismatch in digest response from replicas (see above), the co-ordinator, in this case, node *V*, **sends requests (for the full data set)** to the same sub set of replicas participates in the read (up to the consistency level).
+
+.. image:: 2_read_repair.png
+
+2. During :term:`reconciliation<Reconciliation>`, the co-ordinator (Node *V*) compares full data sets, and **sends updates back** to the out-of-date nodes.
+
+.. image:: 3_read_repair.png
+
+3. Once all updated replicas successfully have responded, the co-ordinator **returns the merged data set** to the client.
+
+.. image:: 4_read_repair.png
+
+Probabilistic Read Repair
+^^^^^^^^^^^^^^^^^^^^^^^^^
+See the appendices below for the detailed flow.
+
+Another read repair mechanism is **probabilistic** read repair, which works as follows:
+
+1. The coordinator checks the value of the ``read_repair_chance`` or ``dclocal_read_repair_chance``. If the probability of a read repair is triggered, it will start the read repair across the entire cluster, or inside the DC, respectively.
+
+.. note::
+
+ These two settings are configured in ``scylla.yaml``.
+ In recent Scylla versions (starting from 4.2.0) default value of both parameters is zero, making Probabilistic Read Repair **off by default**, with a plan to `remove it in the future <https://github.com/scylladb/scylla/issues/3502>`_
+
+2. If the probability of a read repair is triggered, the coordinator sends data request to one of the nodes, digest request to all of the remaining nodes.
+
+.. image:: 5_read_repair.png
+
+3. The coordinator responds to the client as soon as there are enough replies to achieve consistency level, and there is a match.
+
+.. raw:: html
+
+
+
+4. After ALL replicas responses to the coordinator (which may have already responded to the client), the coordinator will compare all responses; and if required (there is a mismatch), the coordinator will ask for the data from all replicas, run reconciliation, and send deltas to any out-of-date replica node(s) - in the background.
+
+.. raw:: html
+
+
+
+5. If a query’s consistency level is more than 1, and a data mismatch is found before consistency level is reached, then the read repair will run in the foreground. **All replica nodes are updated before the data is returned to the client.** However, if data mismatch is found *after* a query’s consistency level is achieved, the update happens in the background, as mentioned above.
+
+The probability of this kind of read repair occurring on a read request is based on the :code:`read_repair_chance`. This :doc:`setting </getting-started/ddl/>`, provided when a table is created, can apply across data centers. The setting specifies the probability that extra nodes (in addition to those required by the consistency level) are queried for the purpose of read repairs.
+
+A similar :doc:`setting </getting-started/ddl/>`, :code:`dclocal_read_repair_chance`, applies only to nodes within the local data center. You can use this setting when conserving traffic between data centers is important.
+
+* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>`
+
+Appendix
+^^^^^^^^
+Flows created with `websequencediagrams.com <http://websequencediagrams.com>`_.
+
+.. image:: 6_Read_Path_with_Read_Repair.png
+
+.. image:: 7_Read_Path_with_Probabilistic_Read_Repair.png
diff --git a/docs/architecture/architecture-fault-tolerance.rst b/docs/architecture/architecture-fault-tolerance.rst
--- a/docs/architecture/architecture-fault-tolerance.rst
+++ b/docs/architecture/architecture-fault-tolerance.rst
@@ -0,0 +1,78 @@
+Scylla Architecture - Fault Tolerance
+=====================================
+
+Scylla replicates data according to a :term:`replication<Replication>` strategy that you choose. This strategy will determine the placement of the replicated data. Scylla runs nodes in a hash ring. All nodes are equal: there are no master, slave, or replica sets.
+
+The :term:`Replication Factor (RF)<Replication Factor (RF)>` is equivalent to the number of nodes where data (rows and partitions) are replicated. Data is replicated to multiple (RF=N) nodes.
+
+An RF of ``1`` means there is only one copy of a row in a cluster and there is no way to recover the data if the node is compromised or goes down. RF=2 means that there are two copies of a row in a cluster. An RF of at least ``3`` is used in most systems or similar.
+
+Data is always replicated automatically. **Read** or **write** operations can occur to data stored on any of the replicated nodes.
+
+.. image:: 1-write_op_RF_3.jpg
+
+In the example above, our client sends a request to write partition *1* to node *V*; 1’s data is replicated to nodes *W*, *X*, and *Z*. We have a Replication Factor (RF) of ``3``. In this drawing, *V* is a coordinator node but not a replicator node. However, replicator nodes can also be coordinator nodes, and often are.
+
+.. image:: 2-read_op_RF_3.jpg
+
+During a :term:`read operation<Read Operation>`, the client sends a request to the coordinator. Effectively because the RF=3, 3 nodes respond to the read request.
+
+The :term:`Consistency Level (CL)<Consistency Level (CL)>` determines how many replicas in a cluster must acknowledge read or :term:`write operations<Write Operation>` before it is considered successful.
+
+For the CQL Shell (:doc:`CQLsh </getting-started/cqlsh>`), the consistency level defaults to ONE for read and write operations.
+
+
+.. note::
+ Regardless of the **Consistency Level**, a write is always sent to *all* replicas, as set by the **Replication Factor**. Consistency Level control *when* a client acknowledged, not how many replicas are updated.
+
+During a write operation, the coordinator communicates with the replicas (the number of which depends on the Replication Factor). The write is successful when the specified number of replicas confirm the write.
+
+.. image:: 3-write_op_RF_3_CL_1.jpg
+
+In the above diagram, the double arrows indicate the write operation request going into the coordinator from the client and the acknowledgment being returned. Since the Consistency Level is one, the coordinator, *V*, must only wait for the write to be sent to and responded by a single node in the cluster which is *W*.
+
+Since RF=3, our partition 1 is also written to nodes *X* and *Z*, but the coordinator does not need to wait for a response from them to confirm a successful write operation. In practice, acknowledgments from nodes *X* and *Z* can arrive to the coordinator at a later time, after the coordinator acknowledges the client.
+
+When our Consistency Level is set to ``QUORUM``, the coordinator must wait for a majority of nodes to acknowledge the write before it is considered successful. Since our Replication Factor is 3, we must wait for 2 acknowledgments (the third acknowledgment does not need to be returned):
+
+.. image:: 4-write_op_RF_3_CL_Quorum.jpg
+
+During a read operation, the coordinator communicates with just enough replicas to guarantee that the required Consistency Level is met. Data is then returned to the client.
+
+
+.. image:: 5-read_op_RF_3_CL_2.jpg
+
+
+
+
+The Consistency Level is tunable per operation in CQL. This is known as :term:`tunable consistency<Tunable Consistency>`. Sometimes response latency is more important, making it necessary to adjust settings on a per-query or operation level to override keyspace or even data center-wide consistency settings. In other words, the Consistency Level setting allows you to choose a point in the consistency vs. latency tradeoff.
+
+.. note:: Quorum is a global consistency level across the *entire* cluster. This means that if you have two data centers, all nodes in both datacenters count towards the quorum majority. For example, there is a cluster with two DCs with three nodes in one DC and two nodes in the other. If the smaller DC fails, requests will still pass under Quorum as 3 > 5/2.
+
+The Consistency Level and Replication Factor both impact performance. The **lower** the Consistency Level and/or Replication Factor, the **faster** the read or write operation. However, there will be less fault tolerance if a node goes down.
+
+The Consistency Level itself impacts availability. A **higher** Consistency Level (more nodes required to be online) means less availability with less tolerance to tolerate node failures. A **lower** Consistency Level means more availability and more fault tolerance.
+
+Refer to the :ref:`Consistency Level table <consistency-levels-reference>` to get information about the Consistency Levels that are available for a read or write operation.
+
+Scylla, as do many distributed database systems, adheres to the :term:`CAP Theorem<CAP Theorem>`. The **CAP Theorem** is the notion that **Consistency**, **Availability** and **Partition Tolerance** of data are mutually dependent in a distributed system. Increasing any 2 of these factors will reduce the third.
+
+Scylla adheres to the CAP theorem in the following way:
+
+.. image:: 6-CAP_Theorem.jpg
+
+Scylla chooses availability and partition tolerance over consistency, such that:
+
+- It’s impossible to be both consistent and highly available during a network partition;
+
+- If we sacrifice consistency, we can be highly available.
+
+You’ll need to design your application around Scylla’s data modeling, but the net result is an application that will never go down.
+
+
+Additional Resources
+--------------------
+
+* :doc:`Consistency Level Console Demo </architecture/console-CL-full-demo>`
+* :doc:`Consistency Levels </getting-started/consistency/>`
+* From Scylla Univeristy: take the `Consistency Level lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/consistency-level-cl/>`_
diff --git a/docs/architecture/compaction/compaction-datawrites.png b/docs/architecture/compaction/compaction-datawrites.png
--- a/docs/architecture/compaction/compaction-datawrites.png
+++ b/docs/architecture/compaction/compaction-datawrites.png
null
diff --git a/docs/architecture/compaction/compaction-leveled.png b/docs/architecture/compaction/compaction-leveled.png
--- a/docs/architecture/compaction/compaction-leveled.png
+++ b/docs/architecture/compaction/compaction-leveled.png
null
diff --git a/docs/architecture/compaction/compaction-size-tiered.png b/docs/architecture/compaction/compaction-size-tiered.png
--- a/docs/architecture/compaction/compaction-size-tiered.png
+++ b/docs/architecture/compaction/compaction-size-tiered.png
null
diff --git a/docs/architecture/compaction/compaction-strategies.rst b/docs/architecture/compaction/compaction-strategies.rst
--- a/docs/architecture/compaction/compaction-strategies.rst
+++ b/docs/architecture/compaction/compaction-strategies.rst
@@ -0,0 +1,244 @@
+============================
+Choose a Compaction Strategy
+============================
+
+
+Scylla implements the following compaction strategies in order to reduce :term:`read amplification<Read Amplification>`, :term:`write amplification<Write Amplification>`, and :term:`space amplification<Space Amplification>`, which causes bottlenecks and poor performance. These strategies include:
+
+* `Size-tiered compaction strategy (STCS)`_ - triggered when the system has enough (four by default) similarly sized SSTables.
+* `Leveled compaction strategy (LCS)`_ - the system uses small, fixed-size (by default 160 MB) SSTables distributed across different levels.
+* `Incremental Compaction Strategy (ICS)`_ - shares the same read and write amplification factors as STCS, but it fixes its 2x temporary space amplification issue by breaking huge sstables into SSTable runs, which are comprised of a sorted set of smaller (1 GB by default), non-overlapping SSTables.
+* `Time-window compaction strategy (TWCS)`_ - designed for time series data; replaced Date-tiered compaction.
+* `Date-tiered compaction strategy (DTCS)`_ - designed for time series data.
+
+This document covers how to choose a compaction strategy and presents the benefits and disadvantages of each one. If you want more information on compaction in general or on any of these strategies, refer to the :doc:`Compaction Overview </kb/compaction>`. If you want an explanation of the CQL commands used to create a compaction strategy, refer to :doc:`Compaction CQL Reference </getting-started/compaction>` .
+
+Learn more in the `Compaction Strategies lesson <https://university.scylladb.com/courses/scylla-operations/lessons/compaction-strategies/>`_ on Scylla University
+
+.. _STCS1:
+
+Size-tiered Compaction Strategy (STCS)
+======================================
+
+The premise of :term:`Size-tiered Compaction Strategy (STCS)<Size-tiered Compaction Strategy>` is to merge SSTables of approximately the same size.
+
+Size-tiered compaction benefits
+-------------------------------
+This is a popular strategy for LSM workloads. It results in a low and logarithmic (in size of data) number of SSTables, and the same data is copied during compaction a fairly low number of times. Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+Size-tiered compaction disadvantages
+------------------------------------
+This strategy has the following drawbacks (particularly with writes):
+
+* Continuously modifying existing rows results in each row being split across several SSTables, making reads slow, which doesn’t happen in :ref:`Leveled compaction <LCS1>`.
+
+* Obsolete data (overwritten or deleted columns) in a very large SSTable remains, wasting space, for a long time, until it is finally merged. In overwrite-intensive loads for example, the overhead can be as much as 400%, as data will be duplicated 4X within a tier. On the other hand, the output SSTable will be the size of a single input SSTable. As a result, you will need 5X the amount of space (4 input SSTables plus one output SSTable), so 400% over the amount of data currently being stored. The allocated space will have to be checked and evaluated as your data set increases in size.
+
+* Compaction requires a lot of temporary space as the new larger SSTable is written before the duplicates are purged. In the worst case up to half the disk space needs to be empty to allow this to happen.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Size-tiered compaction <size-tiered-compaction-strategy-stcs>`.
+
+.. _LCS1:
+
+Leveled Compaction Strategy (LCS)
+=================================
+
+:term:`Leveled Compaction Strategy<Leveled compaction strategy (LCS)>` (LCS) uses small, fixed-size (by default 160 MB) SSTables divided into different levels. Each level represents a run of a number of SSTables.
+
+Leveled Compaction benefits
+---------------------------
+With the leveled compaction strategy, the following benefits are noteworthy:
+
+* SSTable reads are efficient. The great number of small SSTables doesn’t mean we need to look up a key in that many SSTables, because we know the SSTables in each level have disjoint ranges, so we only need to look in one SSTable in each level. In the typical case, only one SSTable needs to be read.
+* The other factors making this compaction strategy efficient are that at most 10% of space will be wasted by obsolete rows, and only enough space for ~10x the small SSTable size needs to be reserved for temporary use by compaction.
+
+Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+Leveled Compaction disadvantages
+--------------------------------
+The downside of this method is there is two times more I/O on writes, so it is not as good for workloads which focus on writing mostly new data.
+
+Only one compaction operation on the same table can run at a time, so compaction may be postponed if there is a compaction already in progress. As the size of the files is not too large, this is not really an issue.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Leveled Compaction <leveled-compaction-strategy-lcs>`.
+
+.. _ICS1:
+
+Incremental Compaction Strategy (ICS)
+=====================================
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. note:: ICS is only available for Scylla Enterprise customers
+
+ICS principles of operation are similar to those of STCS, merely replacing the increasingly larger SSTables in each tier, by increasingly longer SSTable runs, modeled after LCS runs, but using larger fragment size of 1 GB, by default.
+
+Compaction is triggered when there are two or more runs of roughly the same size. These runs are incrementally compacted with each other, producing a new SSTable run, while incrementally releasing space as soon as each SSTable in the input run is processed and compacted. This method eliminates the high temporary space amplification problem of STCS by limiting the overhead to twice the (constant) fragment size, per shard.
+
+Incremental Compaction Strategy benefits
+----------------------------------------
+* Greatly reduces the temporary space amplification which is typical of STCS, resulting in more disk space being available for storing user data.
+* The space requirement for a major compaction with ICS is almost non-existent given that the operation can release fragments at roughly same rate it produces new ones.
+
+If you look at the following screenshot the green line shows how disk usage behaves under ICS when major compaction is issued.
+
+.. image:: /architecture/compaction/screenshot.png
+
+Incremental Compaction Strategy disadvantages
+----------------------------------------------
+
+* Since ICS principles of operation are the same as STCS, its disadvantages are similar to STCS's, except for the temporary space amplification issue.
+
+Namely:
+
+* Continuously modifying existing rows results in each row being split across several SSTables, making reads slow, which doesn’t happen in Leveled compaction.
+* Obsolete data (overwritten or deleted columns) may accumulate across tiers, wasting space, for a long time, until it is finally merged. This can be mitigated by running major compaction from time to time.
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Incremental Compaction <incremental-compaction-strategy-ics>`.
+
+For more information, see the :ref:`Compaction KB Article <incremental-compaction-strategy-ics>`.
+
+.. _TWCS1:
+
+Time-window Compaction Strategy (TWCS)
+======================================
+
+Time-window compaction strategy was introduced in Cassandra 3.0.8 for time-series data as a replacement for `Date-tiered Compaction Strategy (DTCS)`_.
+Time-Window Compaction Strategy compacts SSTables within each time window using `Size-tiered Compaction Strategy (STCS)`_.
+SSTables from different time windows are never compacted together. You set the :ref:`TimeWindowCompactionStrategy <time-window-compactionstrategy-twcs>` parameters when you create a table using a CQL command.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+Time-window Compaction benefits
+-------------------------------
+
+* Keeps entries according to a time range, making searches for data within a given range easy to do, resulting in better read performance
+* Improves over DTCS in that it reduces the number to huge compactions
+* Allows you to expire an entire SSTable at once (using a TTL) as the data is already organized within a time frame
+
+Time-window Compaction deficits
+-------------------------------
+
+* Time-window compaction is **only** ideal for time-series workloads
+
+**To implement this strategy**
+
+Set the parameters for :ref:`Time-window Compaction <time-window-compactionstrategy-twcs>`.
+
+Use the table in `Which strategy is best`_ to determine if this is the right strategy for your needs.
+
+.. _DTCS1:
+
+Date-tiered Compaction Strategy (DTCS)
+======================================
+
+Date-Tiered Compaction is designed for time series data. This strategy was introduced with Cassandra 2.1.
+It is only suitable for time-series data. This strategy is not recommended and has been replaced by :ref:`Time-window Compaction Strategy <TWCS1>`.
+
+.. _which-strategy-is-best:
+
+Which strategy is best
+======================
+
+Every workload type may not work well with every compaction strategy. Unfortunately, the more mixed your workload, the harder it is to pick the correct strategy. This table presents what can be expected depending on the strategy you use for the workload indicated, allowing you to make a more informed decision. Keep in mind that the best choice for our testing may not be the best choice for your environment. You may have to experiment to find which strategy works best for you.
+
+.. _CSM1:
+
+Compaction Strategy Matrix
+--------------------------
+
+The table presents which workload works best with which compaction strategy. In cases where you have the ability to use either STCS or ICS, always choose ICS.
+
+.. list-table::
+ :widths: 20 15 15 15 15 20
+ :header-rows: 1
+
+ * - Workload/Compaction Strategy
+ - Size-tiered
+ - Leveled
+ - Incremental
+ - Time-Window
+ - Comments
+ * - Write-only
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [1]_ and [2]_
+ * - :abbr:`Overwrite (Same data cells overwritten many times)`
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [3]_ and [4]_
+ * - Read-mostly, with few updates
+ - |x|
+ - |v|
+ - |x|
+ - |x|
+ - [5]_
+ * - Read-mostly, with many updates
+ - |v|
+ - |x|
+ - |v|
+ - |x|
+ - [6]_
+ * - Time Series
+ - |x|
+ - |x|
+ - |x|
+ - |v|
+ - [7]_ and [8]_
+
+
+The comments below describe the type of amplification each compaction strategy create on each use case, using the following abbreviations:
+
+* SA - Size Amplification
+* WA - Write Amplification
+* RA - Read Amplification
+
+.. _1:
+
+:sup:`1` When using Size-tiered with write-only loads it will use approximately 2x peak space - :abbr:`SA (Size Amplification)` with Incremental, the SA is much less
+
+.. _2:
+
+:sup:`2` When using Leveled Compaction with write only loads you will experience high Write Amplification - :abbr:`WA (Write Amplification)`
+
+.. _3:
+
+:sup:`3` When using Size-tired or Incremental with Overwrite loads, :abbr:`SA (Size Amplification)` occurs
+
+.. _4:
+
+:sup:`4` When using Leveled Compaction with overwrite loads, :abbr:`WA (Write Amplification)` occurs
+
+.. _5:
+
+:sup:`5` When using Size-tiered with mostly read loads with little updates, :abbr:`SA (Size Amplification)` and :abbr:`RA (Read Amplification)` occurs
+
+.. _6:
+
+:sup:`6` When using Leveled with mostly read loads with many updates, :abbr:`WA (Write Amplification)` occurs in excess
+
+.. _7:
+
+:sup:`7` When using Size-tiered or Incremental with Time Series workloads, :abbr:`SA (Size Amplification)`, :abbr:`RA (Read Amplification)`, and :abbr:`WA (Write Amplification)` occurs.
+
+.. _8:
+
+:sup:`8` When using Leveled with Time Series workloads, :abbr:`SA (Size Amplification)` and :abbr:`WA (Write Amplification)` occurs.
+
+References
+----------
+* :doc:`Compaction Overview </kb/compaction>` - contains in depth information on all of the strategies
+* :doc:`Compaction CQL Reference </getting-started/compaction>` - covers the CQL parameters used for implementing compaction
+* Scylla Summit Tech Talk: `How to Ruin Performance by Choosing the Wrong Compaction Strategy <https://www.scylladb.com/tech-talk/ruin-performance-choosing-wrong-compaction-strategy-scylla-summit-2017/>`_
+
+
diff --git a/docs/architecture/compaction/screenshot.png b/docs/architecture/compaction/screenshot.png
--- a/docs/architecture/compaction/screenshot.png
+++ b/docs/architecture/compaction/screenshot.png
null
diff --git a/docs/architecture/console-CL-full-demo.rst b/docs/architecture/console-CL-full-demo.rst
--- a/docs/architecture/console-CL-full-demo.rst
+++ b/docs/architecture/console-CL-full-demo.rst
@@ -0,0 +1,236 @@
+Consistency Level Console Demo
+==============================
+In this demo, we'll bring up 3 nodes and demonstrate how writes and reads look, with tracing enabled in a cluster where our :term:`Replication Factor (RF)<Replication Factor (RF)>` is set to **3**. We'll change the :term:`Consistency Level (CL)<Consistency Level (CL)>` between operations to show how messages are passed between nodes, and finally take down a few nodes to show failure conditions in a Scylla cluster.
+
+You can also learn more in the `High Availability lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability//>`_ on Scylla University.
+
+
+Note: We use asciinema_ to generate the console casts used in this demo. These asciicasts are more readable than embedded video, and allow you to copy the text or commands directly from the console to your clipboard. We suggest viewing console casts in **fullscreen** to see the properly formatted output.
+
+.. _asciinema: https://asciinema.org
+
+
+Step one: bring up the cluster
+-------------------------------
+
+First, we'll bring up a 3-node docker cluster. You'll see all the nodes eventually read ``UN`` for status. ``U`` means **up**, and ``N`` means **normal**. Read more about :doc:`Nodetool Status </operating-scylla/nodetool-commands/status/>`.
+
+Once all nodes are up, we can run our CQL shell.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/SQ5KW0bYTjXRWPHVkGY97WD1A.js" id="asciicast-SQ5KW0bYTjXRWPHVkGY97WD1A" data-speed="3" data-rows="30" autoplay=1 async></script>
+ </div>
+ </div>
+
+We've run ``nodetool status`` after we've waited for all nodes to come up:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Datacenter: datacenter1
+ =======================
+ Status=Up/Down
+ |/ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 172.17.0.3 127.42 KB 256 65.8% 66a3bfe7-3e90-4859-a394-becc00af1cf2 rack1
+ UN 172.17.0.2 110.58 KB 256 65.5% f66639bf-3259-47f5-8487-602fcb082624 rack1
+ UN 172.17.0.4 118.38 KB 256 68.6% d978ff65-0331-4f27-a129-9be2d7169ad6 rack1
+
+
+Step two: take a single node down, check different consistency levels
+----------------------------------------------------------------------
+
+So, what happens when we take a single node down? Here, we'll take a single node down, check status with ``nodetool``, attempt a write with **ALL** and **QUORUM** consistency levels.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/KhUpcnsWgpu119psj5aHjac0N.js" id="asciicast-KhUpcnsWgpu119psj5aHjac0N" data-speed="3" data-rows="40" async></script>
+ </div>
+ </div>
+
+Note that we've turned tracing off. We can observe that our **CL=ALL** writes will always fail because one of the nodes is down. **CL=QUORUM** operations *could* fail, depending on whether a required partition replica falls on a node that is up or down.
+
+
+Step three: take 2 nodes down, read and write with different consistency levels
+--------------------------------------------------------------------------------
+
+Let's take a second node down and attempt to read and write with QUORUM and ONE consistency levels.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/dkTt8Lopfa6N1VsajcmjUsduK.js" id="asciicast-dkTt8Lopfa6N1VsajcmjUsduK" data-speed="3" data-rows="40" async></script>
+ </div>
+ </div>
+
+With 2 nodes down on our 3 node cluster and **RF=3**, a **CL=QUORUM** will always fail as at least one of the required nodes will always be down. One the other hand, a **CL=ONE** will succeed, as it only requires one up node.
+
+
+Step four: testing different consistency levels with tracing on
+---------------------------------------------------------------
+
+Finally, we'll turn on tracing, and with all our nodes up, write to the table with **CL=ALL** and read from it with **CL=QUORUM**.
+
+.. raw:: html
+
+ <div class="panel callout radius animated asciinema">
+ <div class="row">
+ <script type="text/javascript" src="https://asciinema.org/a/LLOZIhQxX96BXsnrMpr50oUSa.js" id="asciicast-LLOZIhQxX96BXsnrMpr50oUSa" data-speed="3" data-t="103" autoplay=1 data-rows="30" async></script>
+ </div>
+ </div>
+
+
+We've just written a record with our consistency level set to ALL.
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> CONSISTENCY ALL
+
+Consistency level set to ALL.
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> CREATE TABLE users(user_id int PRIMARY KEY, fname text, lname text);
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> TRACING ON
+
+Now Tracing is enabled
+
+.. code-block:: console
+
+ cqlsh:mykeyspace> insert into users(user_id, lname, fname) values (1, 'tzach', 'livyatan');
+
+
+Here's the output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Tracing session: 84deb7a0-9d81-11e7-b770-000000000002
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-19 21:28:46.362000 | 172.17.0.4 | 0
+ Parsing a statement [shard 0] | 2017-09-19 21:28:46.362223 | 172.17.0.4 | 14
+ Processing a statement [shard 0] | 2017-09-19 21:28:46.362604 | 172.17.0.4 | 273
+ Creating write handler for token: -4069959284402364209 | 2017-09-19 21:28:46.362962 | 172.17.0.4 | 755
+ natural: {172.17.0.3, 172.17.0.4, 172.17.0.2} pending: {} [shard 0] | | |
+ Creating write handler with live: {172.17.0.2, 172.17.0.3, 172.17.0.4} | 2017-09-19 21:28:46.362992 | 172.17.0.4 | 784
+ dead: {} [shard 0] | | |
+ Sending a mutation to /172.17.0.2 [shard 0] | 2017-09-19 21:28:46.363171 | 172.17.0.4 | 959
+ Sending a mutation to /172.17.0.3 [shard 0] | 2017-09-19 21:28:46.363298 | 172.17.0.4 | 1090
+ Executing a mutation locally [shard 0] | 2017-09-19 21:28:46.363316 | 172.17.0.4 | 1109
+ Message received from /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.363942 | 172.17.0.3 | 16
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.364225 | 172.17.0.3 | 307
+ Message received from /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.365395 | 172.17.0.2 | 93
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-19 21:28:46.365561 | 172.17.0.2 | 206
+ Mutation handling is done [shard 1] | 2017-09-19 21:28:46.366538 | 172.17.0.2 | 1234
+ Got a response from /172.17.0.2 [shard 0] | 2017-09-19 21:28:46.368064 | 172.17.0.4 | 5858
+ Got a response from /172.17.0.4 [shard 0] | 2017-09-19 21:28:46.369589 | 172.17.0.4 | 7384
+ Mutation handling is done [shard 1] | 2017-09-19 21:28:46.370843 | 172.17.0.3 | 6928
+ Got a response from /172.17.0.3 [shard 0] | 2017-09-19 21:28:46.372486 | 172.17.0.4 | 9964
+ Mutation successfully completed [shard 0] | 2017-09-19 21:28:46.372519 | 172.17.0.4 | 10314
+ Done processing - preparing a result [shard 0] | 2017-09-19 21:28:46.372548 | 172.17.0.4 | 10341
+ Request complete | 2017-09-19 21:28:46.372357 | 172.17.0.4 | 10357
+
+
+With tracing on, we have verbose output. Also, with all nodes up, we should have no errors experiencing a **CL=ALL** write. (Later, we will try different consistency levels with 1 and 2 nodes down.) With **RF=3**, we see all three nodes involved in the interaction. Once the co-ordinator (``172.17.0.4``) has received responses from the two other replicas - ``172.17.0.2`` and ``172.17.0.3`` - as well as itself- the operation is complete.
+
+So what happens when we write under **QUORUM** instead of **ALL**? **QUORUM** means that we only require responses from (Replication Factor/2) + 1 nodes. Our replication factor is 3, therefore only a majority of 2 nodes must provide an acknowledgement for the eventually-consistent write to be considered successful. Below, we observe that our coordinator, after sending two other mutations to replicas ``172.17.0.2`` and ``172.17.0.3``, executes a mutation locally. However, our coordinator only requires a write acknowledgement from itself and ``172.17.0.3`` before ``Mutation successfully completed`` is returned. Note that the response from ``172.17.0.2`` actually comes later.
+
+.. code:: console
+
+ cqlsh:mykeyspace> CONSISTENCY QUORUM
+
+Consistency level set to QUORUM.
+
+.. code:: console
+
+ cqlsh:mykeyspace> insert into users (user_id, fname, lname) values (2, 'john', 'hammink');
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ Tracing session: ccb9d1d0-98d7-11e7-b971-000000000003
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-13 23:03:47.821000 | 172.17.0.4 | 0
+ Parsing a statement [shard 3] | 2017-09-13 23:03:47.821879 | 172.17.0.4 | 1
+ Processing a statement [shard 3] | 2017-09-13 23:03:47.822050 | 172.17.0.4 | 172
+ Creating write handler for token: -3248873570005575792 | 2017-09-13 23:03:47.822160 | 172.17.0.4 | 283
+ natural: {172.17.0.3, 172.17.0.4, 172.17.0.2} pending: {} [shard 3] | | |
+ Creating write handler with live: {172.17.0.2, 172.17.0.3, 172.17.0.4} | 2017-09-13 23:03:47.822171 | 172.17.0.4 | 293
+ dead: {} [shard 3] | | |
+ Sending a mutation to /172.17.0.2 [shard 3] | 2017-09-13 23:03:47.822192 | 172.17.0.4 | 314
+ Sending a mutation to /172.17.0.3 [shard 3] | 2017-09-13 23:03:47.822209 | 172.17.0.4 | 331
+ Executing a mutation locally [shard 3] | 2017-09-13 23:03:47.822214 | 172.17.0.4 | 336
+ Message received from /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.822564 | 172.17.0.2 | 7
+ Message received from /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.822851 | 172.17.0.3 | 5
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.823009 | 172.17.0.2 | 452
+ Mutation handling is done [shard 1] | 2017-09-13 23:03:47.823067 | 172.17.0.2 | 510
+ Sending mutation_done to /172.17.0.4 [shard 1] | 2017-09-13 23:03:47.823734 | 172.17.0.3 | 887
+ Mutation handling is done [shard 1] | 2017-09-13 23:03:47.823744 | 172.17.0.3 | 898
+ Got a response from /172.17.0.4 [shard 3] | 2017-09-13 23:03:47.823984 | 172.17.0.4 | 2106
+ Got a response from /172.17.0.3 [shard 3] | 2017-09-13 23:03:47.824998 | 172.17.0.4 | 3120
+ Mutation successfully completed [shard 3] | 2017-09-13 23:03:47.825003 | 172.17.0.4 | 3125
+ Done processing - preparing a result [shard 3] | 2017-09-13 23:03:47.825054 | 172.17.0.4 | 3176
+ Got a response from /172.17.0.2 [shard 3] | 2017-09-13 23:03:47.825696 | 172.17.0.4 | 3817
+ Request complete | 2017-09-13 23:03:47.824182 | 172.17.0.4 | 3182
+
+
+We can observe that reading under **QUORUM** consistency works similarly. In our example below, our coordinator ``172.17.0.4`` waits for only ``read_data`` from ``172.17.0.2`` (as well as itself earlier: ``read_data: querying locally``) before the read is considered successful. Note that node ``172.17.0.3`` similarly handles ``read_digest`` as ``172.17.0.2`` handles ``read_data``.
+
+.. code:: console
+
+ cqlsh:mykeyspace> CONSISTENCY QUORUM
+
+Consistency level set to QUORUM.
+
+.. code:: console
+
+ cqlsh:mykeyspace> select * from users where user_id = 1;
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ user_id | fname | lname
+ ---------+-------+----------
+ 1 | tzach | livyatan
+
+ (1 rows)
+
+ Tracing session: b11084e0-9e33-11e7-9f6b-000000000003
+
+ activity | timestamp | source | source_elapsed
+ -------------------------------------------------------------------------+----------------------------+------------+---------------
+ Execute CQL3 query | 2017-09-20 18:44:10.926000 | 172.17.0.4 | 0
+ Parsing a statement [shard 3] | 2017-09-20 18:44:10.926442 | 172.17.0.4 | 1
+ Processing a statement [shard 3] | 2017-09-20 18:44:10.926538 | 172.17.0.4 | 97
+ Creating read executor for token -4069959284402364209 | 2017-09-20 18:44:10.926606 | 172.17.0.4 | 165
+ with all: {172.17.0.4, 172.17.0.2, 172.17.0.3} | | |
+ targets: {172.17.0.4, 172.17.0.2, 172.17.0.3} | | |
+ repair decision: DC_LOCAL [shard 3] | | |
+ read_digest: sending a message to /172.17.0.3 [shard 3] | 2017-09-20 18:44:10.926634 | 172.17.0.4 | 193
+ read_data: querying locally [shard 3] | 2017-09-20 18:44:10.926664 | 172.17.0.4 | 223
+ read_data: sending a message to /172.17.0.2 [shard 3] | 2017-09-20 18:44:10.926711 | 172.17.0.4 | 270
+ read_digest: message received from /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.926956 | 172.17.0.3 | 6
+ read_data: message received from /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.927310 | 172.17.0.2 | 7
+ read_digest handling is done, sending a response to /172.17.0.4 [shard 3]| 2017-09-20 18:44:10.927454 | 172.17.0.3 | 505
+ read_data handling is done, sending a response to /172.17.0.4 [shard 3] | 2017-09-20 18:44:10.928248 | 172.17.0.2 | 946
+ read_digest: got response from /172.17.0.3 [shard 3] | 2017-09-20 18:44:10.929873 | 172.17.0.4 | 3432
+ read_data: got response from /172.17.0.2 [shard 3] | 2017-09-20 18:44:10.929880 | 172.17.0.4 | 3439
+ Done processing - preparing a result [shard 3] | 2017-09-20 18:44:10.929934 | 172.17.0.4 | 3493
+ Request complete | 2017-09-20 18:44:10.929503 | 172.17.0.4 | 3503
diff --git a/docs/architecture/fault-tolerance-operations-5.png b/docs/architecture/fault-tolerance-operations-5.png
--- a/docs/architecture/fault-tolerance-operations-5.png
+++ b/docs/architecture/fault-tolerance-operations-5.png
null
diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst
--- a/docs/architecture/index.rst
+++ b/docs/architecture/index.rst
@@ -0,0 +1,24 @@
+Scylla Architecture
+===================
+.. toctree::
+ :titlesonly:
+ :hidden:
+
+ Scylla Ring Architecture <ringarchitecture/index/>
+ Scylla Fault Tolerance <architecture-fault-tolerance>
+ Consistency Level Console Demo <console-CL-full-demo>
+ Scylla Anti-Entropy <anti-entropy/index/>
+ SSTable <sstable/index/>
+ Compaction Strategies <compaction/compaction-strategies>
+ Raft Consensus Algorithm in ScyllaDB </architecture/raft>
+
+
+* :doc:`Scylla Ring Architecture </architecture/ringarchitecture/index/>` - High-Level view of Scylla Ring Architecture
+* :doc:`Scylla Fault Tolerance </architecture/architecture-fault-tolerance>` - Deep dive into Scylla Fault Tolerance
+* :doc:`Consistency Level Console Demo </architecture/console-CL-full-demo>` - Console Demos of Consistency Level Settings
+* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>` - High-Level view of Scylla Anti-Entropy
+* :doc:`SSTable </architecture/sstable/index/>` - Scylla SSTable 2.0 and 3.0 Format Information
+* :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>` - High-level analysis of different compaction strategies
+* :doc:`Raft Consensus Algorithm in ScyllaDB </architecture/raft>` - Overview of how Raft is implemented in ScyllaDB.
+
+Learn more about these topics in the `Scylla University: Architecture lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/>`_.
diff --git a/docs/architecture/raft.rst b/docs/architecture/raft.rst
--- a/docs/architecture/raft.rst
+++ b/docs/architecture/raft.rst
@@ -0,0 +1,185 @@
+=========================================
+Raft Consensus Algorithm in ScyllaDB
+=========================================
+
+Introduction
+--------------
+ScyllaDB was originally designed, following Apache Cassandra, to use gossip for topology and schema updates and the Paxos consensus algorithm for
+strong data consistency (:doc:`LWT </using-scylla/lwt>`). To achieve stronger consistency without performance penalty, ScyllaDB 5.0 is turning to Raft - a consensus algorithm designed as an alternative to both gossip and Paxos.
+
+.. _raft-quorum-requirement:
+
+Quorum Requirement
+-------------------
+
+Raft requires at least a quorum of nodes in a cluster to be available. If multiple nodes fail
+and the quorum is lost, the cluster is unavailable for schema updates. See :ref:`Handling Failures <raft-handliing-failures>`
+for information on how to handle failures.
+
+
+Upgrade Considerations for SyllaDB 5.0 and Later
+==================================================
+
+Note that when you have a two-DC cluster with the same number of nodes in each DC, the cluster will lose the quorum if one
+of the DCs is down.
+**We recommend configuring three DCs per cluster to ensure that the cluster remains available and operational when one DC is down.**
+
+Enabling Raft
+---------------
+
+Enabling Raft in ScyllaDB 5.0
+===============================
+
+.. note::
+ In ScyllaDB 5.0:
+
+ * Raft is an experimental feature.
+ * Raft implementation only covers safe schema changes. See :ref:`Safe Schema Changes with Raft <raft-schema-changes>`.
+
+If you are creating a new cluster, add ``raft`` to the list of experimental features in your ``scylla.yaml`` file:
+
+.. code-block:: yaml
+
+ experimental_features:
+ - raft
+
+If you upgrade to ScyllaDB 5.0 from an earlier version, perform a :doc:`rolling restart </operating-scylla/procedures/config-change/rolling-restart/>`
+updating the ``scylla.yaml`` file for **each node** in the cluster to enable the experimental Raft feature:
+
+.. code-block:: yaml
+
+ experimental_features:
+ - raft
+
+
+When all the nodes in the cluster and updated and restarted, the cluster will begin to use Raft for schema changes.
+
+.. warning::
+ Once enabled, Raft cannot be disabled on your cluster. The cluster nodes will fail to restart if you remove the Raft feature.
+
+Verifying that Raft Is Enabled
+===============================
+You can verify that Raft is enabled on your cluster in one of the following ways:
+
+* Retrieve the list of supported features by running:
+
+ .. code-block:: sql
+
+ cqlsh> SELECT supported_features FROM system.local;
+
+ With Raft enabled, the list of supported features in the output includes ``SUPPORTS_RAFT_CLUSTER_MANAGEMENT``. For example:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ supported_features
+ -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ CDC,CDC_GENERATIONS_V2,COMPUTED_COLUMNS,CORRECT_COUNTER_ORDER,CORRECT_IDX_TOKEN_IN_SECONDARY_INDEX,CORRECT_NON_COMPOUND_RANGE_TOMBSTONES,CORRECT_STATIC_COMPACT_IN_MC,COUNTERS,DIGEST_FOR_NULL_VALUES,DIGEST_INSENSITIVE_TO_EXPIRY,DIGEST_MULTIPARTITION_READ,HINTED_HANDOFF_SEPARATE_CONNECTION,INDEXES,LARGE_PARTITIONS,LA_SSTABLE_FORMAT,LWT,MATERIALIZED_VIEWS,MC_SSTABLE_FORMAT,MD_SSTABLE_FORMAT,ME_SSTABLE_FORMAT,NONFROZEN_UDTS,PARALLELIZED_AGGREGATION,PER_TABLE_CACHING,PER_TABLE_PARTITIONERS,RANGE_SCAN_DATA_VARIANT,RANGE_TOMBSTONES,ROLES,ROW_LEVEL_REPAIR,SCHEMA_TABLES_V3,SEPARATE_PAGE_SIZE_AND_SAFETY_LIMIT,STREAM_WITH_RPC_STREAM,SUPPORTS_RAFT_CLUSTER_MANAGEMENT,TOMBSTONE_GC_OPTIONS,TRUNCATION_TABLE,UDA,UNBOUNDED_RANGE_TOMBSTONES,VIEW_VIRTUAL_COLUMNS,WRITE_FAILURE_REPLY,XXHASH
+
+* Retrieve the list of experimental features by running:
+
+ .. code-block:: sql
+
+ cqlsh> SELECT value FROM system.config WHERE name = 'experimental_features'
+
+ With Raft enabled, the list of experimental features in the output includes ``raft``.
+
+.. _raft-schema-changes:
+
+Safe Schema Changes with Raft
+-------------------------------
+In ScyllaDB, schema is based on :doc:`Data Definition Language (DDL) <../getting-started/ddl>`. In earlier ScyllaDB versions, schema changes were tracked via the gossip protocol, which might lead to schema conflicts if the updates are happening concurrently.
+
+Implementing Raft eliminates schema conflicts and allows full automation of DDL changes under any conditions, as long as a quorum
+of nodes in the cluster is available. The following examples illustrate how Raft provides the solution to problems with schema changes.
+
+* A network partition may lead to a split-brain case, where each subset of nodes has a different version of the schema.
+
+ With Raft, after a network split, the majority of the cluster can continue performing schema changes, while the minority needs to wait until it can rejoin the majority. Data manipulation statements on the minority can continue unaffected, provided the :ref:`quorum requirement <raft-quorum-requirement>` is satisfied.
+
+* Two or more conflicting schema updates are happening at the same time. For example, two different columns with the same definition are simultaneously added to the cluster. There is no effective way to resolve the conflict - the cluster will employ the schema with the most recent timestamp, but changes related to the shadowed table will be lost.
+
+ With Raft, concurrent schema changes are safe.
+
+
+
+In summary, Raft makes schema changes safe, but it requires that a quorum of nodes in the cluster is available.
+
+
+.. _raft-handliing-failures:
+
+Handling Failures
+------------------
+Raft requires a quorum of nodes in a cluster to be available. If one or more nodes are down, but the quorum is live, reads, writes,
+and schema udpates proceed unaffected.
+When the node that was down is up again, it first contacts the cluster to fetch the latest schema and then starts serving queries.
+
+The following examples show the recovery actions depending on the number of nodes and DCs in your cluster.
+
+Examples
+=========
+
+.. list-table:: Cluster A: 1 datacenter, 3 nodes
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1 node
+ - Schema updates are possible and safe.
+ - Try restarting the node. If the node is dead, :doc:`replace it with a new node </operating-scylla/procedures/cluster-management/replace-dead-node/>`.
+ * - 2 nodes
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - Restart at least 1 of the 2 nodes that are down to regain quorum. If you can’t recover at least 1 of the 2 nodes, contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+ * - 1 datacenter
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DC comes back online, restart the nodes. If the DC does not come back online and nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. list-table:: Cluster B: 2 datacenters, 6 nodes (3 nodes per DC)
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1-2 nodes
+ - Schema updates are possible and safe.
+ - Try restarting the node(s). If the node is dead, :doc:`replace it with a new node </operating-scylla/procedures/cluster-management/replace-dead-node/>`.
+ * - 3 nodes
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - Restart 1 of the 3 nodes that are down to regain quorum. If you can’t recover at least 1 of the 3 failed nodes, contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+ * - 1DC
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DCs come back online, restart the nodes. If the DC fails to come back online and the nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. list-table:: Cluster C: 3 datacenter, 9 nodes (3 nodes per DC)
+ :widths: 20 40 40
+ :header-rows: 1
+
+ * - Failure
+ - Consequence
+ - Action to take
+ * - 1-4 nodes
+ - Schema updates are possible and safe.
+ - Try restarting the nodes. If the nodes are dead, :doc:`replace them with new nodes </operating-scylla/procedures/cluster-management/replace-dead-node-or-more/>`.
+ * - 1 DC
+ - Schema updates are possible and safe.
+ - When the DC comes back online, try restarting the nodes in the cluster. If the nodes are dead, :doc:`add 3 new nodes in a new region </operating-scylla/procedures/cluster-management/add-dc-to-existing-dc/>`.
+ * - 2 DCs
+ - Cluster is not fully opetarional. The data is available for reads and writes, but schema changes are impossible.
+ - When the DCs come back online, restart the nodes. If at least one DC fails to come back online and the nodes are lost, :doc:`restore the latest cluster backup into a new cluster </operating-scylla/procedures/backup-restore/restore/>`. You can contact `ScyllaDB support <https://www.scylladb.com/product/support/>`_ for assistance.
+
+
+.. _raft-learn-more:
+
+Learn More About Raft
+----------------------
+* `The Raft Consensus Algorithm <https://raft.github.io/>`_
+* `Achieving NoSQL Database Consistency with Raft in ScyllaDB <https://www.scylladb.com/tech-talk/achieving-nosql-database-consistency-with-raft-in-scylla/>`_ - A tech talk by Konstantin Osipov
+* `Making Schema Changes Safe with Raft <https://www.scylladb.com/presentations/making-schema-changes-safe-with-raft/>`_ - A Scylla Summit talk by Konstantin Osipov (register for access)
+* `The Future of Consensus in ScyllaDB 5.0 and Beyond <https://www.scylladb.com/presentations/the-future-of-consensus-in-scylladb-5-0-and-beyond/>`_ - A Scylla Summit talk by Tomasz Grabiec (register for access)
+
+
diff --git a/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif b/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
--- a/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
+++ b/docs/architecture/ringarchitecture/CodeCogsEqn-2.gif
null
diff --git a/docs/architecture/ringarchitecture/CodeCogsEqn.gif b/docs/architecture/ringarchitecture/CodeCogsEqn.gif
--- a/docs/architecture/ringarchitecture/CodeCogsEqn.gif
+++ b/docs/architecture/ringarchitecture/CodeCogsEqn.gif
null
diff --git a/docs/architecture/ringarchitecture/index.rst b/docs/architecture/ringarchitecture/index.rst
--- a/docs/architecture/ringarchitecture/index.rst
+++ b/docs/architecture/ringarchitecture/index.rst
@@ -0,0 +1,121 @@
+Scylla Ring Architecture - Overview
+===================================
+
+Scylla is a database that scales out and up. Scylla adopted much of its distributed scale-out design from the Apache Cassandra project (which adopted distribution concepts from Amazon Dynamo and data modeling concepts from Google BigTable).
+
+In the world of big data, a single node cannot hold the entire dataset and thus, a cluster of nodes is needed.
+
+A Scylla :term:`cluster<Cluster>` is a collection of :term:`nodes<Node>`, or Scylla instances, visualized as a ring. All of the nodes should be homogenous using a shared-nothing approach. This article describes the design that determines how data is distributed among the cluster members.
+
+A Scylla :term:`keyspace<Keyspace>` is a collection of tables with attributes that define how data is replicated on nodes. A keyspace is analogous to a database in SQL. When a new keyspace is created, the user sets a numerical attribute, the :term:`replication factor<Replication Factor (RF)>`, that defines how data is replicated on nodes. For example, an :abbr:`RF (Replication Factor)` of 2 means a given token or token range will be stored on 2 nodes (or replicated on one additional node). We will use an RF value of 2 in our examples.
+
+A :term:`table<Table>` is a standard collection of columns and rows, as defined by a schema. Subsequently, when a table is created, using CQL (Cassandra Query Language) within a keyspace, a primary key is defined out of a subset of the table’s columns.
+
+The table in the diagram below can thus be defined in CQL as follows:
+
+.. code-block:: SQL
+
+ CREATE TABLE users (
+ ID int,
+ NAME text,
+ ADDRESS text,
+ PHONE text,
+ PHONE_2 text,
+ PRIMARY KEY (ID)
+ );
+
+
+In a CQL table definition, the :term:`primary key<Primary Key>` clause specifies, at a minimum, a single column :term:`partition key<Partition key>` and may also specify :term:`clustering key<Clustering Key>` columns. The primary key uniquely identifies each partition/row combination in the table, while the clustering keys dictate how the data (rows) are sorted within a given partition. For more information, see our CQL :ref:`documentation <create-table-statement>`.
+
+A **row** is a container for columns associated with a primary key. In other words, a primary key represents one or more columns needed to fetch data from a CQL table.
+
+.. image:: ring-architecture-1.png
+
+A :term:`token<Token>` is a value in a range, used to identify both nodes and partitions. The :term:`partition key<Partition key>` is the unique identifier for a partition, and represented as a token which is hashed from the :term:`primary key<Primary Key>`.
+
+A :term:`partition<Partition>` is a subset of data that is stored on a node and replicated across nodes. There are two ways to consider a partition. In **CQL**, a partition appears as a group of sorted rows, and is the unit of access for queried data, given that most queries access a single partition. On the **physical layer**, a partition is a unit of data stored on a node and is identified by a :term:`partition key<Partition Key>`.
+
+In the diagram above, there are 3 partitions shown, with the partition keys of **101**, **103**, and **104**.
+
+A :term:`partition key<Partition key>` is the primary means of looking up a set of rows that comprise a partition. A partition key serves to identify the node in the cluster that stores a given partition, as well as to distribute data across nodes in a cluster.
+
+The :term:`partitioner<Partitioner>`, or **partition hash function**, using a partition key, determines where data is stored on a given node in the cluster. It does this by computing a token for each partition key. By default, the partition key is hashed using the Murmur3 hashing function.
+
+.. image:: ring-architecture-2.png
+
+The hashed output of the partition key determines its placement within the cluster.
+
+.. image:: ring-architecture-3.png
+
+The figure above illustrates an example 0-1200 token range divided evenly amongst a three node cluster.
+
+Scylla, by default, uses the Murmur3 partitioner. With the MurmurHash3 function, the 64-bit hash values (produced for the partition key) range from |From| to |To|. This explains why there are also negative values in our ``nodetool ring`` output below.
+
+.. |From| image:: CodeCogsEqn.gif
+.. |To| image:: CodeCogsEqn-2.gif
+
+.. image:: ring-architecture-4.png
+
+In the drawing above, each number represents a token range. With a replication factor of 2, we see that each node holds one range from the previous node, and one range from the next node.
+
+Note, however, that Scylla exclusively uses a Vnode-oriented architecture. A :term:`Virtual node` represents a contiguous range of tokens owned by a single Scylla node. A physical node may be assigned multiple, non-contiguous Vnodes.
+
+Scylla’s implementation of a Vnode oriented architecture provides several advantages. First of all, rebalancing a cluster is no longer required when adding or removing nodes. Secondly, as rebuilding can stream data from all available nodes (instead of just the nodes where data would reside on a one-token-per-node setup), Scylla can rebuild faster.
+
+.. image:: ring-architecture-5.png
+
+The proportion of Vnodes assigned to each node in a cluster is configurable in the ``num_tokens`` setting of ``scylla.yaml``; the default is ``256``.
+
+You can use the ``nodetool`` command to describe different aspects of your nodes, and the token ranges they store. For example,
+
+``$ nodetool ring <keyspace>``
+
+Outputs all tokens of a node, and displays the token ring information_. It produces output as follows for a single datacenter:
+
+.. _information: /operating-scylla/nodetool-commands/ring/
+
+.. code-block:: shell
+
+ Datacenter: datacenter1
+ =======================
+ Address Rack Status State Load Owns Token
+ 9156964624790153490
+ 172.17.0.2 rack1 Up Normal 110.52 KB 66.28% -9162506483786753398
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9154241136797732852
+ 172.17.0.4 rack1 Up Normal 118.32 KB 67.04% -9144708790311363712
+ 172.17.0.4 rack1 Up Normal 118.32 KB 67.04% -9132191441817644689
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9080806731732761568
+ 172.17.0.3 rack1 Up Normal 127.32 KB 66.69% -9017721528639019717
+ ...
+
+Here we see that, for each token, it shows the address of the node, which rack it is on, the status (``Up`` or ``Down``), the state, the load, and the token. The ``Owns`` column shows the percentage of the ring (the keyspace) actually handled by that node.
+
+``$ nodetool describering <keyspace>``
+
+Shows the token ranges of a given keyspace. That output, on a three node cluster, looks like this:
+
+.. code-block:: shell
+
+ Schema Version:082bce63-be30-3e6b-9858-4fb243ce409c
+ TokenRange:
+ TokenRange(start_token:9143256562457711404, end_token:9156964624790153490, endpoints:[172.17.0.4], rpc_endpoints:[172.17.0.4], endpoint_details:[EndpointDetails(host:172.17.0.4, datacenter:datacenter1, rack:rack1)])
+ TokenRange(start_token:9081892821497200625, end_token:9111351650740630104, endpoints:[172.17.0.4], rpc_endpoints:[172.17.0.4], endpoint_details:[EndpointDetails(host:172.17.0.4, datacenter:datacenter1, rack:rack1)])
+ ...
+
+We can also get information on our cluster with
+
+``$ nodetool describecluster``
+
+.. code-block:: shell
+
+ Cluster Information:
+ Name: Test Cluster
+ Snitch: org.apache.cassandra.locator.SimpleSnitch
+ Partitioner: org.apache.cassandra.dht.Murmur3Partitioner
+ Schema versions:
+ 082bce63-be30-3e6b-9858-4fb243ce409c: [172.17.0.2, 172.17.0.3, 172.17.0.4]
+
+Learn more in the `Cluster Node Ring lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/cluster-node-ring/>`_ on Scylla University
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/ringarchitecture/ring-architecture-1.png b/docs/architecture/ringarchitecture/ring-architecture-1.png
--- a/docs/architecture/ringarchitecture/ring-architecture-1.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-1.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-2.png b/docs/architecture/ringarchitecture/ring-architecture-2.png
--- a/docs/architecture/ringarchitecture/ring-architecture-2.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-2.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-3.png b/docs/architecture/ringarchitecture/ring-architecture-3.png
--- a/docs/architecture/ringarchitecture/ring-architecture-3.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-3.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-4.png b/docs/architecture/ringarchitecture/ring-architecture-4.png
--- a/docs/architecture/ringarchitecture/ring-architecture-4.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-4.png
null
diff --git a/docs/architecture/ringarchitecture/ring-architecture-5.png b/docs/architecture/ringarchitecture/ring-architecture-5.png
--- a/docs/architecture/ringarchitecture/ring-architecture-5.png
+++ b/docs/architecture/ringarchitecture/ring-architecture-5.png
null
diff --git a/docs/architecture/sstable/_common/sstable_what_is.rst b/docs/architecture/sstable/_common/sstable_what_is.rst
--- a/docs/architecture/sstable/_common/sstable_what_is.rst
+++ b/docs/architecture/sstable/_common/sstable_what_is.rst
@@ -0,0 +1,27 @@
+:term:`Sorted Strings Table (SSTable)<SSTable>` is the persistent file format used by Scylla and Apache Cassandra. SSTable is saved as a persistent, ordered, immutable set of files on disk.
+Immutable means SSTables are never modified; they are created by a MemTable flush and are deleted by a compaction.
+The location of Scylla SSTables is specified in scylla.yaml ``data_file_directories`` parameter (default location: ``/var/lib/scylla/data``).
+
+SSTable 3.0 (mc format) is more efficient and requires less disk space than the SSTable 2.x. SSTable version support is as follows:
+
+
+.. list-table::
+ :widths: 33 33 33
+ :header-rows: 1
+
+ * - SSTable Version
+ - Scylla Enterprise Version
+ - Scylla Open Source Version
+ * - 3.x ('md')
+ - 2021.1
+ - 4.3 and above
+ * - 3.0 ('mc')
+ - 2019.1, 2020.1
+ - 3.x, 4.1, 4.2
+ * - 2.2 ('la')
+ - N/A
+ - 2.3
+ * - 2.1.8 ('ka')
+ - 2018.1
+ - 2.2
+
diff --git a/docs/architecture/sstable/index.rst b/docs/architecture/sstable/index.rst
--- a/docs/architecture/sstable/index.rst
+++ b/docs/architecture/sstable/index.rst
@@ -0,0 +1,19 @@
+Scylla SSTable Format
+=====================
+
+.. toctree::
+ :hidden:
+
+ sstable2/index
+ sstable3/index
+
+.. include:: _common/sstable_what_is.rst
+
+* In Scylla Enterprise 2021.1, Scylla 4.3 and above, *md* format is enabled by default.
+
+* In Scylla 3.1 and above, *mc* format is enabled by default.
+
+For more information on each of the SSTable formats, see below:
+
+* :doc:`SSTable 2.x <sstable2/index>`
+* :doc:`SSTable 3.x <sstable3/index>`
diff --git a/docs/architecture/sstable/sstable2/index.rst b/docs/architecture/sstable/sstable2/index.rst
--- a/docs/architecture/sstable/sstable2/index.rst
+++ b/docs/architecture/sstable/sstable2/index.rst
@@ -0,0 +1,24 @@
+Scylla SSTable - 2.x
+====================
+
+.. toctree::
+ :hidden:
+
+ sstable-compression
+ sstable-data-file
+ sstable-format
+ sstable-interpretation
+ sstable-summary-file
+
+.. include:: ../_common/sstable_what_is.rst
+
+For more information about Scylla 2.x SSTable formats, see below:
+
+
+* :doc:`SSTable Compression <sstable-compression>` - Deep dive into Scylla/Apache Cassandra SSTable Compression
+* :doc:`SSTable Data File <sstable-data-file>` - Deep dive into Scylla/Apache Cassandra SSTable format
+* :doc:`SSTable format in Scylla <sstable-format>` - Scylla SSTables are compatible to those in Apache Cassandra 2.1.8, but why there are more of them?
+* :doc:`SSTable Interpretation <sstable-interpretation>` - Deep dive into Scylla/Apache Cassandra SSTable Interpretation in Scylla
+* :doc:`SSTable Summary File <sstable-summary-file>` - Deep dive into Scylla/Apache Cassandra SSTable Summary file format
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-compression.rst b/docs/architecture/sstable/sstable2/sstable-compression.rst
--- a/docs/architecture/sstable/sstable2/sstable-compression.rst
+++ b/docs/architecture/sstable/sstable2/sstable-compression.rst
@@ -0,0 +1,100 @@
+SSTable Compression
+===================
+
+Chunked Compression of Data File
+................................
+
+SSTables compression allows to optionally compress the :doc:`SSTables Data
+File </architecture/sstable/sstable2/sstable-data-file>`, which is the biggest part of the
+SSTable (the other parts, like the index, cannot be compressed).
+
+Because random-access read from the data file is important, Apache Cassandra implements
+*chunked* compression: The uncompressed file is divided into chunks of a
+configurable fixed size (usually 64 KB), and each of these chunks is
+compressed separately and written to the compressed data file, followed
+by a 4-byte checksum of the compressed chunk. The compressed chunks have
+different lengths, so we need to remember their offsets so we can seek
+to an arbitrary chunk containing our desired uncompressed data. This
+list of offsets is stored in a separate Compression Info File, described
+below.
+
+The Compression Info File
+.........................
+
+ References: **CompressedRandomAccessReader.java**,
+ **CompressionMetadata.java**, **CompressionParameters.java**.
+
+The Compression Info File only exists if the data file is compressed.
+The Compression Info File specifies the compression parameters that the
+decompressor needs to know (such as the compression algorithm and chunk
+size), and the list of offsets of the compressed chunks in the
+compressed file:
+
+.. code:: c
+
+ struct short_string {
+ be16 length;
+ char value[length];
+ };
+
+::
+
+ struct option {
+ short_string key;
+ short_string value;
+ };
+
+::
+
+ struct compression_info {
+ short_string compressor_name;
+ be32 options_count;
+ option options[options_count];
+ be32 chunk_length;
+ be64 data_length;
+ be32 chunk_count;
+ be64 chunk_offsets[chunk_count];
+ };
+
+The **compressor\_name** can be one of three strings supported by
+Apache Cassandra: "LZ4Compressor", "SnappyCompressor" or "DeflateCompressor".
+Cassandra defaults to LZ4Compressor, but a user could choose any one of
+the three.
+
+The **options** may contain additional options for the decompressor, But
+usually no options are listed, and only one option exists:
+"crc\_check\_chance", whose value is a floating-point string which
+defaults (if the option doesn't appear) to "1.0", and determines the
+probability that we verify the checksum of a compressed chunk we read.
+
+**chunk\_length** is the length of the chunks into which the original
+uncompressed data is divided before compression. The decompressor needs
+to know this chunk size as well, so when given a desired byte offset in
+the original uncompressed file, it can determine which chunk it needs to
+uncompress. The chunk length defaults to 65536 bytes, but can be any
+power of two.
+
+**data\_length** is the total length of the uncompressed data.
+
+**chunks\_offsets** is the list of offsets of the compressed chunks
+inside the compressed file. To read data in position ``p`` in the
+uncompressed file, we calculates ``p / chunk_length`` is the
+uncompressed chunk number. The compressed version of this check is now
+begins in ``chunk_offsets[p / chunk_length]``. The compressed chunk ends
+4 bytes before the beginning of the next chunk (because, as explained
+above, every compressed chunk is followed by a 4-byte checksum).
+
+The Compressed Data File
+........................
+
+As explained above, the compressed data file is a sequence of compressed
+chunked, each a compressed version of a fixed-sized (``chunk_length``
+from the Compression Info File) uncompressed chunk. Each compressed
+chunk is followed by a be32 (big-endian 4-byte integer) Adler32 checksum
+of the *compressed* data, which can be used to verify the data hasn't
+been corrupted
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/sstable/sstable2/sstable-data-file.rst b/docs/architecture/sstable/sstable2/sstable-data-file.rst
--- a/docs/architecture/sstable/sstable2/sstable-data-file.rst
+++ b/docs/architecture/sstable/sstable2/sstable-data-file.rst
@@ -0,0 +1,263 @@
+SSTable Data File
+=================
+
+The *data file* contains a part of the actual data stored in the
+database. Basically, it is one long list of rows, where each row lists
+its key and its columns.
+
+The data file alone does not provide an efficient means to efficiently
+find a row with a specific key. For this, the ``SSTables Index File`` and
+:doc:`SSTables Summary File </architecture/sstable/sstable2/sstable-summary-file>` exist. Additionally
+the ``SSTables Bloom Filter File`` exists
+for quickly determining if a specific key exists in this SSTable
+(an Apache Cassandra table is written incrementally to several separate SSTables).
+
+The data file may be compressed as described in :doc:`SSTables
+Compression </architecture/sstable/sstable2/sstable-compression>`. As
+we explain there, the compression layer offers random access to the
+uncompressed data, like an ordinary file, so here we can assume the data
+file is uncompressed.
+
+This document explains the format of the sstable data file, but glosses
+over the question of how higher-level Apache Cassandra concepts - such as
+clustering columns, static columns, collections, etc., translate to
+sstable data. This is discussed in :doc:`SSTables
+interpretation </architecture/sstable/sstable2/sstable-interpretation>`.
+
+The Data File
+.............
+
+The data file is nothing more than a long sequence of rows:
+
+.. code:: cpp
+
+ struct data_file {
+ struct row[];
+ };
+
+The code usually skips directly to the position of a row with a desired
+key (using the index file), so we'll want an API to efficiently read
+this whole row. We'll probably (TODO: find what uses this...
+compaction?) also need an API to efficiently iterate over successive
+rows (without rereading the same disk blocks).
+
+Rows
+....
+
+ References: **SSTableIdentityIterator.java**, constructor.
+ **DeletionTime.java**
+
+Each row begins with a header which includes the row's *key*, if (and
+when) it was deleted, followed by a sequence of *cells* (column names
+and values) or other types of *atoms* described below. The last atom in
+a row is special row-end atom, marking the end of the row.
+
+.. code:: cpp
+
+ struct row {
+ be16 key_length;
+ char key[key_length];
+ struct deletion_time deletion_time;
+ struct atom atoms[];
+ };
+
+Note that the row definition does not include its length - the reader
+reads the row incrementally until reaching the row-end atom.
+Alternatively, if we want to read an entire row into memory before
+parsing it, we can figure out its length using the ``SSTables Index File``. If we
+reached this row from a particular index entry, the next index entry
+will point to the byte after the end of this row.
+
+If we reached a particular row through the index, we may already know we
+have the right key, and can skip the key at the beginning of the row
+without bothering to deserialize it.
+
+The deletion\_time structure determines whether this is a row tombstone
+- i.e., whether the whole row has been deleted, and if so, when:
+
+.. code:: c
+
+ struct deletion_time {
+ be32 local_deletion_time;
+ be64 marked_for_delete_at;
+ };
+
+The special value LIVE = (MAX\_BE32, MIN\_BE64), i.e., the bytes 7F FF
+FF 80 00 00 00 00 00 00 00, is the default for live, undeleted, rows.
+``marked_for_delete_at`` is a timestamp (typically in microseconds since
+the UNIX epoch) after which data should be considered deleted. If set to
+MIN\_BE64, the data has not been marked for deletion at all.
+``local_deletion_time`` is the local server timestamp (in *seconds*
+since the UNIX) epoch when this tombstone was created - this is only
+used for purposes of purging the tombstone after gc\_grace\_seconds have
+elapsed.
+
+Atoms (cells, end-of-row, and more)
+...................................
+
+ References: **OnDiskAtom.java**:deserializeFromSSTable(),
+ **ColumnSerializer**:deserializeColumnBody(),
+ **RangeTombstone**:deserializeBody().
+
+A row's value is a list of *atoms*, each of which is usually a cell (a
+column name and value) or an end-of-row atom, but can also be additional
+types of atoms as explained below.
+
+Each atom, of any type begins with a column name, a byte string with
+16-bit length. If the length of the name is 0 (in other words, the atom
+begins with two null bytes), this is an end-of-row atom, as the other
+atom types always have non-empty names. Note that, yes, the column names
+are repeated in each and every row. The compression layer eliminates
+much of the disk-space waste, but the overhead of parsing this verbose
+encoding remains.
+
+.. code:: cpp
+
+ struct atom {
+ be16 column_name_length;
+ char column_name[column_name_length];
+ }
+
+If the atom has a non-empty name, it is *not* an end-of-row, and
+following column\_name appears a single byte *mask*:
+
+.. code:: cpp
+
+ enum mask {
+ DELETION_MASK = 0x01,
+ EXPIRATION_MASK = 0x02,
+ COUNTER_MASK = 0x04,
+ COUNTER_UPDATE_MASK = 0x08,
+ RANGE_TOMBSTONE_MASK = 0x10,
+ };
+
+.. code:: cpp
+
+ struct nonempty_atom : atom {
+ char mask;
+ }
+
+The mask determines which type of atom this is:
+
+If mask & (RANGE\_TOMBSTONE\_MASK \| COUNTER\_MASK \| EXPIRATION\_MASK)
+== 0, we have a regular cell. This has a 64-bit timestamp (can be used
+to decide which value of a cell is most recent), and a value, serialized
+into a byte array with 32-bit length:
+
+.. code:: cpp
+
+ struct cell_atom : nonempty_atom {
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+(Note: The COUNTER\_UPDATE\_MASK and DELETION\_MASK might be turned in
+for cell\_atom, modifying its meaning).
+
+if mask & RANGE\_TOMBSTONE\_MASK, we have a
+
+.. code:: cpp
+
+ struct range_tombstone_atom : nonempty_atom {
+ u16 last_column_length;
+ char last_column_name[last_column_length];
+ struct deletion_time dt;
+ };
+
+Such a range-tombstone atom effects not just the single column
+column\_name, but the range between column\_name and last\_column\_name
+(as usual, this range is defined using the underlying comparator of the
+column name type).
+
+if mask & COUNTER\_MASK, we have a
+
+.. code:: cpp
+
+ struct counter_cell_atom : nonempty_atom {
+ be64 timestamp_of_last_delete;
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+if mask & EXPIRATION\_MASK, we have a
+
+.. code:: cpp
+
+ struct expiring_cell_atom : nonempty_atom {
+ be32 ttl;
+ be32 expiration;
+ be64 timestamp;
+ be32 value_length;
+ char value[value_length];
+ };
+
+Note that it is not valid to have more than one RANGE\_TOMBSTONE\_MASK,
+COUNTER\_MASK or EXPIRATION\_MASK on the same atom.
+
+Name and Value Serialization
+............................
+
+ References: **Composite.java**, **CompositeType.java**.
+
+It is important to remember that both column *names* and *values*
+described above are stored as a byte strings (preceded by its length,
+16-bit or 32-bit). But in Apache Cassandra, both names and values may have
+various types (as determined by the CQL schema), and those are
+**serialized** to a byte string before the byte string is serialized to
+disk as part of the atom.
+
+This has a surprising effect on the encoding of column names in the data
+file. Starting with Apache Cassandra 1.2, unless the table is created "WITH
+compact storage", column names are always *composite*, i.e., a sequence
+of components. A composite column name is serialized to a byte array
+like this:
+
+.. code:: cpp
+
+ struct serialized_composite_name {
+ struct {
+ be16 component_length;
+ char[] component; // of length component_length
+ char end_of_component; // usually 0, can be -1 (\0xff) or 1 (\0x01) - see below.
+ } component[];
+ }
+
+Then ``end_of_component`` is usually 0, but can also be -1 or 1 for
+specifying not a specific column but ranges, as explained in comments in
+Composite.java and CompositeType.java.
+
+So the surprising result is that even single-component column names
+produce wasteful double-serialization (unless the tables has WITH
+compact storage): For example, the column name "age", a composite name
+with just one component, is first serialized into ``\0 \3 a g e \0`` and
+then this serialized string is written as the column name, preceded by
+its own length, 6: ``\0 \6 \0 \3 a g e \0``.
+
+Note that the above means we need to know, when reading an sstable,
+whether column names are composite or not. Therefore the sstable reader
+need to know if this table has "WITH compact storage" or not.
+
+CQL Row Marker
+..............
+
+In some cases (namely, tables built through CQL without "WITH compact
+storage"), each row will contain a bizarre extra cell called a "CQL Row
+Marker" which the Apache Cassandra developers (who apparently don't care about
+wasting space...) added to allow a row to remain even if all its columns
+are deleted. It's worth knowing that this extra cell exists, as its
+existence might surprise the uninitiated.
+
+The "CQL Row Marker" is a normal cell in a row, which has an "empty
+composite" name and an empty value. Note that the cell's column name is
+**not** empty - it can't be (an empty name is an end-of-row marker).
+Rather, it is a composite name with one empty-string component. Such a
+composite name is serialized, as explained above, to ``\0 \0 \0`` - the
+first two null bytes are the empty component's length, and at the end we
+have the additional null added in the serialization. This
+three-null-bytes is what gets used as the column name
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-format.rst b/docs/architecture/sstable/sstable2/sstable-format.rst
--- a/docs/architecture/sstable/sstable2/sstable-format.rst
+++ b/docs/architecture/sstable/sstable2/sstable-format.rst
@@ -0,0 +1,17 @@
+SSTable format in Scylla
+========================
+
+
+Scylla supports the same SSTable format as Apache Cassandra 2.1.8, which means
+you can simply place SSTables from a Cassandra data directory into a
+Scylla data directory—and it will just work
+
+Looking more carefully, you will see that Scylla maintains more,
+smaller, SSTables than Cassandra does. On Scylla, each core manages its
+own subset of SSTables. This internal sharding allows each core (shard)
+to work more efficiently, avoiding the complexity and delays of multiple
+cores competing for the same data
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable2/sstable-interpretation.rst b/docs/architecture/sstable/sstable2/sstable-interpretation.rst
--- a/docs/architecture/sstable/sstable2/sstable-interpretation.rst
+++ b/docs/architecture/sstable/sstable2/sstable-interpretation.rst
@@ -0,0 +1,531 @@
+SSTable Interpretation
+======================
+
+.. role:: raw-latex(raw)
+ :format: latex
+..
+
+**Topic: Internals**
+
+**Audience: Devops professionals, architects**
+
+The SSTables Data File contains rows of data. This document discusses
+how to interpret the various fields described in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file/>` in the context of Scylla, and how to
+convert this data into Scylla's native data structure:
+**mutation\_partition**.
+
+SSTable Rows
+............
+
+Each row in the SSTable isn't necessarily a full row of data. Rather, it
+is just a **mutation**, a list of changed (added or deleted) columns and
+their new values (or "tombstone" for a deleted column), and a timestamp
+for each such change (this timestamp is used for reconciling conflicting
+mutations). The full data row needed by a request will be composed from
+potentially multiple sstables and/or the in-memory table(s).
+
+As we'll explain below when discussing clustering columns, the best term
+for what we read from one row in the SSTable isn't a "row", but rather a
+**partition**.
+
+For these reasons, Scylla's internal representation for a row we read
+from the SSTable is called ``class mutation_partition``.
+
+Column Names
+............
+
+As explained in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file>`, the
+sstable row (a mutation partition) is a list of *cells* (column values).
+Each cell is preceded by the full column name. This was considered a
+good idea when Apache Cassandra was designed to support rows with many and
+arbitrary columns, but Scylla is more oriented toward the CQL use case
+with a known schema. So Scylla's rows do not store the full column name,
+but rather store a numeric ID which points to the known list of columns
+from the schema. So as we read column names from the SSTable in form of IDs,
+we need to translate the IDs into names by looking them up in the schema.
+
+Composite Column Names
+......................
+
+But the column names mentioned in the sstable cells usually aren't a
+field name mentioned in the schema, and additional processing needs to
+be done to the column names which we read from the SSTable.
+
+The first issue is that starting with Apache Cassandra 1.2 (and unless
+``WITH COMPACT STORAGE`` is used), column names aren't plain strings,
+but each is rather rather a *composite* name - a short list of name
+components. See :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file>` for this
+list's on-disk encoding, but for simplicity of exposition let's use the
+convention of writing a composite name as **(part1:part2:...)**
+
+Things are simplest when no clustering keys are involved; Then, cell
+names have just one component. For example, consider the table created
+with the following CQL command:
+
+::
+
+ CREATE TABLE harels (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO harels (name, age) VALUES ('nadav', 40);
+
+In this table, we have a row with the key "nadav", and in this row, one
+cell, with the column name "age" encoded as a single-component composite
+string **(age)** (on disk, ``\003 a g e \0``). This only component,
+"age", can be looked up in the table's schema, and converted to a column
+ID in the ``mutation_partition``, as explained above.
+
+CQL Row Marker
+..............
+
+As explained in :doc:`SSTables Data File </architecture/sstable/sstable2/sstable-data-file/>`,
+Apache Cassandra always (except when a COMPACT table is used and other esoteric
+exceptions) adds to each row an empty-named and empty-valued bogus
+"cell", to solve various problems involving finding a row after its only
+column has been deleted. This is also explained in a comment in
+UpdateStatement.Java, and in
+https://issues.apache.org/jira/browse/CASSANDRA-4361.
+
+For example, if we inspect with ``tools/bin/sstable2json`` the table
+created in the previous example, we find:
+
+::
+
+ {"key": "nadav",
+ "cells": [["","",1426688662900463],
+ ["age","40",1426688662900463]]}
+
+The first cell, with the empty name ("") and value (the second ""), is
+the "CQL Row Marker". As usual, the empty name "" shown by sstable2json
+is not actually an empty string, but a composite with one empty
+component, **()** (serialized on disk as ``'\000 \000 \000'``).
+
+I hope we can simply ignore these CQL Row Marker cells, and not
+duplicate them in Scylla's internal format. We just need a different way
+to allow empty rows (a row with only a key, but no data columns) to
+exist, to circumvent the problems mentioned in CASSANDRA-4361 and the
+comment in UpdateStatement.Java.
+
+Clustering Keys
+...............
+
+When the table has a clustering key, column names in the sstable no
+longer have a single component:
+
+::
+
+ USE try1;
+
+::
+
+ CREATE TABLE harels2 (
+ name text,
+ nick text,
+ age int,
+ PRIMARY KEY (name, nick)
+ ) WITH compression = {};
+
+::
+
+ INSERT INTO harels2 (name, nick, age) VALUES ('nadav', 'nyh', 40);
+
+Note how name and nick form the primary key, but the CQL syntax
+specifies that the **partition key** is name, and the **clustering key**
+is nick. This means that different tables entries that have the same
+name (but different nick) will appear in the same partition, i.e., in
+the same sstable row. Inside that partition, different nicks can appear,
+each with its own age. To see what this looks like in the sstable we
+again use the *sstable2json* tool, and see:
+
+::
+
+ {"key": "nadav",
+ "cells": [["nyh:","",1427032626839065],
+ ["nyh:age","40",1427032626839065]]}
+
+In other words, the composite column name (nyh:age) is used to store the
+age for the nick nyh, and a different column would be used to store some
+other nick's age. Note how in (nyh:age), the "nyh" is not one of the CQL
+column names, but rather the *value* of the clustering column nick, and
+only the last component, "age", is an actual name of a field from the
+CQL schema.
+
+In Scylla nomenclature, this single **partition** (with key
+name="nadav") has multiple **rows**, each with a different value of the
+clustering key (nick). Each of these rows has, as usual, columns whose
+names are the fields from the CQL schema (and as explained above, are
+kept as column IDs, not names).
+
+So when converting an sstable row into a ``mutation_partition``, we need
+to consult the schema to look for a clustering key. If "nick" is the
+clustering key, we shouldn't look as usual for cells named (nick).
+Instead, we expect *every* cell name to have >=2 components, where the
+first component is a value of nick, and the second component an actual
+column name. In the ``mutation_partition`` object, we need to insert
+multiple ``row`` objects, where each row corresponds to one value of the
+first component.
+
+The silly cell with key **(nyh:)** (empty second component) and empty
+value is the "CQL Row Marker" described above, which appears for each
+*row* (combination of partition key and clustering key) separately.
+
+Static Columns
+..............
+
+A static column is a special column which is shared by all rows of the
+same partition. As we saw above, the case of multiple rows per partition
+happens when there is a clustering column. When Datastax introduced
+static columns in Cassandra 2.0.6, they used the following example
+(http://www.datastax.com/dev/blog/cql-in-2-0-6):
+
+::
+
+ CREATE TABLE bills (
+ user text,
+ balance int static,
+ expense_id int,
+ amount int,
+ PRIMARY KEY (user, expense_id)
+ );
+
+This is a table of bills (amounts that certain users need to pay).
+According to the "PRIMARY KEY" line, the partition key is "user", and
+"expense\_id" is the clustering key; This means that there will be a
+partition (sstable row) for each user, and for each such partition, we
+can have multiple expenses (*rows*), each with a different
+clustering-key expense\_id, and corresponding amount. But the "balance"
+column is for all the different expenses of the same user.
+
+So if we insert one expense for 'user1', and set user1's balance::
+
+ INSERT INTO bills (user, balance) VALUES ('user1', 17);
+ INSERT INTO bills (user, expense_id, amount) VALUES ('user1', 1, 8);
+
+What is written to the sstable looks like this (as usual, output from
+``sstable2json``):
+
+::
+
+ {"key": "user1",
+ "cells": [[":balance","17",1428849747953348],
+ ["1:","",1428849747970947],
+ ["1:amount","8",1428849747970947]]}
+
+The (1:amount) and (1:) is what we already saw above, the new thing here
+is the (:balance), a static column.
+
+So sstables have static columns specially marked by an empty first
+component of the composite cell name. We need to verify that each such
+cell actually corresponds to a known static column from the table's
+schema, and collect all these static columns into one row
+(``_static_row``) stored in Scylla's ``mutation_partition``.
+
+TODO: CompositeType.java explains that static columns do not really have
+an empty first component (size 0), but rather the first component has
+the fake size STATIC\_MARKER = 0xFFFF (65536). We need to verify this.
+
+Compound Clustering Key
+.......................
+
+When the clustering key is compound, i.e., composed of multiple columns,
+the SSTable column names will contain more than two components. For
+example consider:
+
+::
+
+ USE try1;
+ CREATE TABLE bills3 (
+ user text,
+ expense_id int,
+ year int,
+ amount int,
+ PRIMARY KEY (user, year, expense_id)
+ );
+
+::
+
+ INSERT INTO bills3 (user, year, expense_id, amount) VALUES ('user1', 2015, 1, 8);
+
+Here as usual, the first column name in "PRIMARY KEY", user, is the
+partition key, but the two others, year and expense\_id are both
+clustering columns, forming a compound clustering key. I.e., each
+partition contains several rows, each defined by (and sorted by) the
+pair (year, expense\_id).
+
+The resulting SSTable row is:
+
+::
+
+ {"key": "user1",
+ "cells": [["2015:1:","",1428853746711253],
+ ["2015:1:amount","8",1428853746711253]]}
+
+Note how the column name "amount" is now prefixed by two components, the
+values of the two clustering columns. Of course, a schema can have any
+number of clustering columns and as a result, expect that number of
+prefix components in the SSTable's column names.
+
+As before, all but the last column-name component are expected to be
+values of the clustering-key of the various rows inside the partition,
+and only the last component is a column name to be looked up in the
+schema. It's safer, though, to consult with the schema to see the number
+of clustering columns instead of guessing it as the number of components
+minus one. This is a good sanity check, and also necessary when
+collections are concerned (see below).
+
+Compound Partition Key
+......................
+
+The row key read from the SSTable can also be a composite (a list of
+components) if the schema says the partition key is compound. For
+example:
+
+::
+
+ CREATE TABLE bills2 (
+ user text,
+ expense_id int,
+ amount int,
+ PRIMARY KEY ((user, expense_id))
+ );
+ INSERT INTO bills (user, expense_id, amount) VALUES ('user1', 1, 8);
+
+Note the extra pair of parenthesis in the "PRIMARY KEY" specification,
+which says that expense\_id is part of the partition key, not a
+clustering ey.
+
+The key of each SSTable row is now the pair (user, expense\_id), a
+composite with two components.
+
+TODO: Print the resulting SSTable
+
+Collections
+...........
+
+The encoding of *collections* in SSTables is more complex.
+
+Consider this table definition with a column which is a *set*
+collection:
+
+::
+
+ CREATE TABLE col2 (
+ user text,
+ favorites set<text>,
+ PRIMARY KEY (user)
+ );
+
+::
+
+ INSERT INTO col2 (user, favorites) VALUES ('user1', {'raindrops', 'kittens'});
+
+The resulting SSTable row is:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428855312063525],
+ ["favorites:_","favorites:!",1428855312063524,"t",1428855312],
+ ["favorites:6b697474656e73","",1428855312063525],
+ ["favorites:7261696e64726f7073","",1428855312063525]]}
+
+Here we also have two components in the column names, but we need to
+know this is not the case of a clustering key ("favorites" isn't a value
+of a clustering column) but that of a collection. We need to consult the
+schema to tell the two cases apart (in this case, there are no
+clustering columns, so no component needs to be treated as a clustering
+column, so when we see two components, it must be a collection).
+
+In a set, we have a cell for each item in the collection, and *second*
+component of the cell's name is the serialized value. E.g., in our case,
+the byte array "kittens" is shown by sstable2json in hex
+(6b697474656e73) - in the actual SSTable the hex does not appear (there
+is the length of the string followed by the actual bytes). The value of
+each of these cells is empty for a *set* (for other types of collections
+it is not empty - see below).
+
+The weird cell in the beginning of the above sstable2json output (with
+``favorites:_``) is not a normal cell - this is how sstable prints a
+*range tombstone*, whose range is between the start of "favorites:" and
+the end of "favorites:", the markedForDeleteAt value is 1428855312063524
+and localDeletionTime is 1428855312. The need for this range tombstone
+appears to be as follows: Because each of the collection's items is a
+separate cell, when we *set* the collection (as in the INSERT command we
+used) the intention is to delete any old item in the collection, if
+there are any, and add the new items. The range tombstone takes care of
+deleting all the old items.
+
+The actual sstable doesn't have the "\_" or "!" characters printed by
+sstable2json. What it really has is ``"\00\09favorites\ff"`` and
+:raw-latex:`\0`0:raw-latex:`\0`9favorites:raw-latex:`\0`1". I.e., each
+of these two column names has only one component, but instead of ending
+as usual with the end-of-component byte :raw-latex:`\0`0, the first ends
+with :raw-latex:`\ff `(START) and the second ends with :raw-latex:`\0`1
+(END). This means the range tombstone spans everything between the first
+column and the last, as indeed desired.
+
+The second type of collection, the **map**, is similar to the **set**,
+just the value is not empty but rather the desired value in the map. For
+example,
+
+::
+
+ CREATE TABLE col4 (
+ user text,
+ favorites map<text,int>,
+ PRIMARY KEY (user)
+ ) WITH compression = {};
+ INSERT INTO col4 (user, favorites) VALUES ('user1', {'raindrops' : 1, 'kittens' : 2});
+
+We see in the SSTable with sstable2json:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428864848550739],
+ ["favorites:_","favorites:!",1428864848550738,"t",1428864848],
+ ["favorites:6b697474656e73","00000002",1428864848550739],
+ ["favorites:7261696e64726f7073","00000001",1428864848550739]]}
+
+I.e., indeed exactly the same as the representation of the set, except
+the cell's values are the desired 1 and 2. The way the values are
+printed above as strings ("0000002") is just an artifact of how
+sstable2json works - the value is represented in the SSTable as an
+actual serialized int (32-bit length 4, followed by 4 bytes of the
+integer's representation) as expected.
+
+For the ordered **list** collection, things are similar, but not quite
+the same because of the need to keep the desired item order:
+
+::
+
+ CREATE TABLE col1 (
+ user text,
+ favorites list<text>,
+ PRIMARY KEY (user)
+ );
+ INSERT INTO col1 (user, favorites) VALUES ('user1', ['raindrops', 'kittens']);
+
+The resulting SSTable row is now:
+
+::
+
+ {"key": "user1",
+ "cells": [["","",1428854738475900],
+ ["favorites:_","favorites:!",1428854738475899,"t",1428854738],
+ ["favorites:c2bcd290e12d11e49cac000000000000","7261696e64726f7073",1428854738475900],
+ ["favorites:c2bcd291e12d11e49cac000000000000","6b697474656e73",1428854738475900]]}
+
+Note how this time, the items ("raindrops" and "kittens") are the value
+of the cell, not in the column name. In the column name we have some
+long strings intended to sort in the requested list order. These long
+hex strings are misrepresented by sstable2json - they are not a hex
+string but rather a 16-byte UUID.
+
+To merely keep the list items in order, Apache Cassandra could have used small
+integers instead of these UUIDs. But these UUIDs have an additional
+benefit: as http://www.datastax.com/dev/blog/cql3\_collections explains,
+Apache Cassandra wishes to allow efficient *append* and *prepend* operations to
+an existing list - without reading the existing list first (i.e., the
+append/prepend is a fast write-only mutation, not a slow
+read-modify-write operation). To achieve that, Apache Cassandra uses signed
+time-UUIDs as the list sort string - with positive times used for append
+operations, and negative for prepend operations. This ensures that, for
+example, a later append always sorts after an earlier append - without
+the append having to know which items already exist in the list.
+
+Scylla's internal storage of a collection in a mutation is the
+``class collection_mutation``, and we need to convert the above
+described representation into that class. TODO: I still can't figure out
+exactly what is the internal structure of our collection\_mutation
+(which hides behind an opaque byte array), or what functions we are
+supposed to call to build one).
+
+Cells with Expiration Time
+..........................
+
+An SSTable cell may have an expiration time, as explained
+http://docs.datastax.com/en/cql/3.1/cql/cql\_using/use\_expire\_c.html.
+Such a cell is marked by the EXPIRATION\_MASK bit in the mask byte, and
+in addition to the cell's normal fields, has two additional fields,
+"ttl" and "expiration", both 32-bit and measured in seconds. "ttl" is
+the original time-to-live (number of seconds until expiration) specified
+when the cell was created, and "expiration" is the absolute time when
+the cell should be expired (in seconds since the Unix Epoch).
+
+The following CQL example creates a cell with a time-to-live of 3600
+seconds:
+
+::
+
+ CREATE TABLE ttl (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO ttl (name, age) VALUES ('nadav', 40) USING TTL 3600;
+
+sstable2json prints the resulting SSTable row as:
+
+::
+
+ {"key": "nadav",
+ "cells": [["","",1430151018675502,"e",3600,1430154618],
+ ["age","40",1430151018675502,"e",3600,1430154618]]}
+
+Note how each of cells (the cql row marker, and our actual data cell)
+have a TTL of 3600 seconds, and an expiration time calculated by adding
+3600 to the current time on the server. The fact that the row marker
+also got this TTL is not certain to be a good thing - see discussion in
+https://issues.apache.org/jira/browse/CASSANDRA-5762.
+
+Cell Tombstone
+..............
+
+We've already discussed row tombstones (marking the deletion of an
+entire row) and range tombstone (marking the deletion of a range of
+columns). We can also have a cell tombstone, marking the deletion of a
+single cell. A deleted cell is encoded in the SSTable like a normal
+cell, except the mask has the DELETION\_MASK bit, and the *value* of the
+cell contains the serialized ``local_deletion_time`` (the local server
+time in seconds since the epoch), which is probably only needed for the
+purpose of purging the tombstone after gc\_grace\_seconds have elapsed.
+
+To create an sstable with a deleted cell in Apache Cassandra, consider creating
+a table with some data:
+
+::
+
+ CREATE TABLE deleted (
+ name text,
+ age int,
+ PRIMARY KEY (name)
+ );
+ INSERT INTO deleted (name, age) VALUES ('nadav', 40);
+
+Then flushing this data to an SSTable (with
+``bin/nodetool flush keyspacename``), and then deleting the cell we
+added:
+
+::
+
+ DELETE age FROM deleted WHERE name = 'nadav';
+
+When the second SSTable is flushed, it will have a cell tombstone.
+sstable2json shows the second SSTable like this:
+
+::
+
+ {"key": "nadav",
+ "cells": [["age",1430200516,1430200516937621,"d"]]}
+
+Note how the cell has the DELETION\_MASK bit (written as a "d"), its
+"value" is the local-deletion-time, 1430200516, and as usual it has a
+timestamp
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
diff --git a/docs/architecture/sstable/sstable2/sstable-summary-file.rst b/docs/architecture/sstable/sstable2/sstable-summary-file.rst
--- a/docs/architecture/sstable/sstable2/sstable-summary-file.rst
+++ b/docs/architecture/sstable/sstable2/sstable-summary-file.rst
@@ -0,0 +1,37 @@
+SSTable Summary File
+====================
+
+SSTable Summary file format
+
+.. code:: c
+
+ struct summary_entry {
+ char key[...]; // variable-length.
+ be64 position;
+ };
+
+.. code:: c
+
+ struct summary_la {
+ struct header {
+ be32 min_index_interval;
+ be32 size;
+ be64 memory_size;
+ be32 sampling_level;
+ be32 size_at_full_sampling;
+ } header;
+
+::
+
+ le32 positions[header.size];
+ summary_entry entries[header.size];
+
+ be32 first_key_size;
+ char first_key[first_key_size];
+
+ be32 last_key_size;
+ char last_key[last_key_size];
+ };
+
+.. include:: /rst_include/architecture-index.rst
+
diff --git a/docs/architecture/sstable/sstable3/index.rst b/docs/architecture/sstable/sstable3/index.rst
--- a/docs/architecture/sstable/sstable3/index.rst
+++ b/docs/architecture/sstable/sstable3/index.rst
@@ -0,0 +1,32 @@
+Scylla SSTable - 3.x
+====================
+
+.. toctree::
+ :hidden:
+
+ sstables-3-data-file-format
+ sstables-3-statistics
+ sstables-3-summary
+ sstables-3-index
+ sstable-format
+
+.. include:: ../_common/sstable_what_is.rst
+
+* In Scylla 3.1 and above, mc format is enabled by default.
+
+* In Scylla 3.0, mc format is disabled by default and can be enabled by adding the ``enable_sstables_mc_format`` parameter as 'true' in ``scylla.yaml`` file.
+
+For example:
+
+.. code-block:: shell
+
+ enable_sstables_mc_format: true
+
+
+For more information on Scylla 3.x SSTable formats, see below:
+
+* :doc:`SSTable 3.0 Data File Format <sstables-3-data-file-format>`
+* :doc:`SSTable 3.0 Statistics <sstables-3-statistics>`
+* :doc:`SSTable 3.0 Summary <sstables-3-summary>`
+* :doc:`SSTable 3.0 Index <sstables-3-index>`
+* :doc:`SSTable 3.0 Format in Scylla <sstable-format>`
diff --git a/docs/architecture/sstable/sstable3/sstable-format.rst b/docs/architecture/sstable/sstable3/sstable-format.rst
--- a/docs/architecture/sstable/sstable3/sstable-format.rst
+++ b/docs/architecture/sstable/sstable3/sstable-format.rst
@@ -0,0 +1,16 @@
+SSTable 3.0 Format in Scylla
+============================
+
+Scylla supports the same SSTable format as Apache Cassandra 3.0.
+You can simply place SSTables from a Cassandra data directory into a Scylla uploads directory
+and use the ``nodetool refresh`` command to ingest their data into the table.
+
+Looking more carefully, you will see that Scylla maintains more,
+smaller, SSTables than Cassandra does. On Scylla, each core manages its
+own subset of SSTables. This internal sharding allows each core (shard)
+to work more efficiently, avoiding the complexity and delays of multiple
+cores competing for the same data
+
+.. include:: /rst_include/architecture-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst b/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-data-file-format.rst
@@ -0,0 +1,555 @@
+SSTables 3.0 Data File Format
+=============================
+
+.. versionadded:: 3.0
+
+This article aims at describing the format of data files introduced in Cassandra 3.0. The data file is the file that actually stores the data managed by the database. As important as it is, this file does not come alone. There are other files that altogether constitute a set of components sufficient for manipulating the stored data.
+The following table outlines the types of files used by Cassandra SSTables 3.0:
+
+============================================================ =========================== =======================================================================================
+File Type Typical Name Description
+============================================================ =========================== =======================================================================================
+Compression information mc-1-big-CompressionInfo.db Contains information about the compression algorithm, if used
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Data file mc-1-big-Data.db Stores the actual data
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Checksum file mc-1-big-Digest.crc32 Contains a checksum of the data file
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Bloom filter mc-1-big-Filter.db Contains a Bloom filter to check whether particular data may be stored in the data file
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Index mc-1-big-Index.db Contains the primary index of data for easier search
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Statistics mc-1-big-Statistics.db Stores aggregated statistics about the data
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Summary mc-1-big-Summary.db Provides sampling of the index file (can be seen as "coarse-grained" index)
+------------------------------------------------------------ --------------------------- ---------------------------------------------------------------------------------------
+Table of contents mc-1-big-TOC.txt Lists all the files for the current SSTable
+============================================================ =========================== =======================================================================================
+
+This document focuses on the data file format but also refers to other components in parts where information stored in them affects the way we read/write the data file.
+
+Note that the file on-disk format applies both to the "mc" and "md" SSTable format versions.
+The "md" format only fixed the semantics of the (min|max)_clustering_key fields in the SSTable Statistics file, which are now valid for describing the accurate range of clustering prefixes present in the SSTable.
+See `SSTables 3.0 Statistics File Format <architecture/sstable/sstable3/sstables-3-statistics/>`_ for more details.
+
+Overview
+........
+
+The storage format has been significantly revamped in Cassandra 3.0 compared to the 2.x series. The primary driver for that was the fact that the previous storage format has been devised long before CQL and did not reflect its concepts and abstractions. This, in turn, hindered various fixes and led to suboptimal disk space usage.
+
+To understand what that means, you can refer to the :doc:`SSTables 2.x data file format </architecture/sstable/sstable2/sstable-data-file>` description. In brief, in 2.x every data file is a sequence of partitions (called "rows" in pre-CQL terminology) where each partition is more or less a sequence of cells (or, more precisely, atoms with a majority of them being cells). There is no notion of columns or rows (in CQL terminology) at this level. Each cell has its full name comprised of the clustering prefix (values of all the clustering columns) followed by the non-PK column name.
+
+This scheme causes a lot of duplication since for every row in a given partition determined by a set of clustering columns values those values are stored in names of all the cells that belong to this row. For composite primary keys with long clustering columns values that would mean a lot of disk space wasted for no good reason. Another consequence is that the storage engine has to recognize and group cells from the row itself without knowing in advance their count or overall size.
+
+SSTables 3.0 format addresses this by re-arranging the way data is stored. Now every partition is comprised of rows. Each row is defined by its clustering columns values and consists of a number of cells that all share those clustering columns values as their name prefix. So now one can reason about the data file as a sequence of partitions where partition consists of rows that consist of cells, whereas before it was a sequence of partitions with each partition consisting of cells. This is oversimplified but helpful for understanding the high-level picture of changes.
+
+SSTables 3.0 data file format relies heavily on the table schema. It contains information about PK and non-PK columns, corresponding data types and width (fixed-width vs. variable-width), clustering columns ordering and so on.
+
+Let's examine in more detail how the data representation looks in 3.0.
+
+.. _sstables-3-building-blocks:
+
+Building Blocks
+...............
+
+Before we describe the data format in every detail, let's define a few concepts that are used throughout the whole SSTables 3.0 specification. They act as building blocks for the new format and are responsible for noticeable space savings compared to the old one.
+
+Variable Length Integers (Varints)
+----------------------------------
+
+Variable length integers are inspired by Google Protocol Buffers internal representation for serialised integers. They can save a significant amount of memory/space if the majority of serialised integer values are relatively small.
+
+The internal representation of varints is explained in great detail in this `article`_.
+The main idea is that variable-length integers occupy between 1 and 9 bytes and smaller values require fewer bytes so the format is efficient for storing many relatively small values.
+
+.. _article: https://haaawk.github.io/2018/02/26/sstables-variant-integers.html
+
+In the structures below, `varint` will indicate an integer stored in its variable-length representation on the disk according to the described encoding.
+
+Delta Encoding
+--------------
+
+A lot of values stored in a data file represent timestamps or TTL which values are microseconds since UNIX epoch. Those values are quite large and as such don't benefit much from being stored as varints. The idea that allows reducing timestamp/TTL values footprint is to only store the full value of the minimal timestamp/TTL per a set of objects. For other objects that have a different timestamp/TTL, we store its delta from the minimal value. The delta is typically much smaller and thus has a better chance to occupy fewer bytes upon serialisation.
+Varints can be used for storing deltas just fine.
+
+Optional Items
+--------------
+
+In order to save more disk space, some items can be omitted during serialisation. The presence or absence of a particular optional item is typically indicated by a flag or, in some cases, can be easily deduced in some way from the preceding data.
+These items are marked as optional below. Keep in mind this is **not** `optional`_ but rather merely a convention to mark the items that may not be present in a particular data file.
+
+.. _`optional`: http://en.cppreference.com/w/cpp/utility/optional
+
+The Data File Layout
+....................
+
+The data file itself, just as before, is no more than a plain sequence of serialised partitions:
+
+.. code:: cpp
+
+ struct data_file {
+ struct partition[];
+ };
+
+Partition
+---------
+
+References:
+
+* `Clusterable.java`_
+
+.. _`Clusterable.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Clusterable.java/
+
+* `ClusteringPrefix`_
+
+.. _`ClusteringPrefix`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ClusteringPrefix.java/
+
+* `ClusteringComparator`_
+
+.. _`ClusteringComparator`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ClusteringComparator.java/
+
+* `Unfiltered.java`_
+
+.. _`Unfiltered.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/Unfiltered.java/
+
+When talking about partitions in SSTables, one needs to keep in mind that those partitions contain information about the updates to data and **not** the final state of data. That is, every partition in SSTables is a collection of records (commonly referred to as **mutations**) that have been applied sequentially to modify (insert, update or delete) the data in the data partition with a given partition key.
+
+A partition consists of a header, an optional static row and a sequence of clusterable objects:
+
+.. code:: cpp
+
+ struct partition {
+ struct partition_header header;
+ optional<struct row> static_row; // Has IS_STATIC flag set
+ struct unfiltered unfiltereds[];
+ };
+
+
+The ``partition_header`` contains partition key and deletion information, just as in 2.x formats.
+
+The optional ``static_row`` is only present if there have been inserts to the table's static column(s). If no inserts are present in the Memtable that is flushed into the SSTable, the static row is not present even though the table schema may contain static columns. Static row structure is given below, for now, it suffices to say that it only differs from regular (non-static) rows in that it doesn't have a clustering prefix.
+
+An unfiltered object is an object that can be ordered by the clustering prefix using a ``clustering_comparator`` according to its clustering values and the schema-induced ordering.
+
+.. code:: cpp
+
+ struct unfiltered {
+ };
+
+
+Any unfiltered data in a partition is either a row or a ``range_tombstone_marker``. We will examine both of them below.
+
+Partition Header
+----------------
+
+Reference:
+
+`ColumnIndex.java, writePartitionHeader`_
+
+.. _`ColumnIndex.java, writePartitionHeader`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/ColumnIndex.java/
+
+The `partition_header` format has not changed since 2.x and is defined as:
+
+.. code:: cpp
+
+ struct partition_header {
+ be16 key_length;
+ byte key[key_length];
+ struct deletion_time deletion_time;
+ };
+
+The ``deletion_time`` structure determines whether this is a partition tombstone - i.e., whether the whole partition has been deleted, and if so, when:
+
+.. code:: cpp
+
+ struct deletion_time {
+ be32 local_deletion_time;
+ be64 marked_for_delete_at;
+ };
+
+The special value LIVE = (MAX_BE32, MIN_BE64), i.e., the bytes `7F FF FF FF 80 00 00 00 00 00 00 00`, is the default for live, undeleted, partitions. ``marked_for_delete_at`` is a timestamp (typically in microseconds since the UNIX epoch) after which data should be considered deleted. If set to MIN_BE64, the data has not been marked for deletion at all. ``local_deletion_time`` is the local server timestamp (in seconds since the UNIX) epoch when this tombstone was created - this is only used for purposes of purging the tombstone after ``gc_grace_seconds`` have elapsed.
+
+Row
+---
+
+References:
+
+`UnfilteredSerializer.java, serialize`_
+
+.. _`UnfilteredSerializer.java, serialize`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/UnfilteredSerializer.java#L125/
+
+A `row` is represented with the following layout:
+
+.. code:: cpp
+
+ struct row {
+ byte flags;
+ optional<byte> extended_flags;
+ // only present for non-static rows
+ optional<struct clustering_block[]> clustering_blocks;
+ varint row_body_size;
+ varint prev_unfiltered_size; // for backward traversing
+ optional<struct liveness_info> liveness_info;
+ optional<struct delta_deletion_time> deletion_time;
+ optional<varint[]> missing_columns;
+ cell[] cells;
+ };
+
+Row Flags
+---------
+
+The first byte `flags` is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class row_flags {
+ // Signal the end of the partition. Nothing follows a <flags> field with that flag.
+ END_OF_PARTITION = 0x01,
+ // Whether the encoded unfiltered is a marker or a row. All following flags apply only to rows.
+ IS_MARKER = 0x02,
+ // Whether the encoded row has a timestamp (i.e. its liveness_info is not empty).
+ HAS_TIMESTAMP = 0x04,
+ // Whether the encoded row has some expiration info (i.e. if its liveness_info contains TTL and local_deletion).
+ HAS_TTL = 0x08,
+ // Whether the encoded row has some deletion info.
+ HAS_DELETION = 0x10,
+ // Whether the encoded row has all of the columns from the header present.
+ HAS_ALL_COLUMNS = 0x20,
+ // Whether the encoded row has some complex deletion for at least one of its complex columns.
+ HAS_COMPLEX_DELETION = 0x40,
+ // If present, another byte is read containing the "extended flags" below.
+ EXTENSION_FLAG = 0x80
+ };
+
+
+If `EXTENSION_FLAG` is set, the following byte `extended_flags` is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class row_extended_flags {
+ // Whether the encoded row is a static. If there is no extended flag, the row is assumed not static.
+ IS_STATIC = 0x01,
+ // Whether the row deletion is shadowable. If there is no extended flag (or no row deletion), the deletion is assumed not shadowable. This flag is deprecated - see CASSANDRA-11500.
+ // This flag is not supported by Scylla and SSTables that have this flag set fail to be loaded.
+ HAS_SHADOWABLE_DELETION_CASSANDRA = 0x02,
+ // A Scylla-specific flag (not supported by Cassandra) that indicates the presence of a shadowable tombstone.
+ // See below for details
+ HAS_SHADOWABLE_DELETION_SCYLLA = 0x80,
+ };
+
+As mentioned earlier, every partition may or may not have a static row. If present, the static row precedes any other rows or range tombstone markers and has ``EXTENSION_FLAG`` set in ``flags`` and ``IS_STATIC`` set in ``extended_flags``. As you might expect, the static row will not have any clustering information just by its definition.
+
+Clustering Blocks
+-----------------
+
+If ``IS_STATIC`` is not set or ``extended_flags`` byte is missing, the row has a list of clustering blocks that represents the values of clustering columns.
+
+.. code:: cpp
+
+ struct clustering_block {
+ varint clustering_block_header;
+ simple_cell[] clustering_cells;
+ };
+
+
+To build the clustering blocks, all the clustering columns are split into batches of 32 (or less for the last batch).
+To calculate the ``clustering_block_header``, for each column in batch, the information about if its cell is null or empty is encoded using 2 bits in a 64-bit integer. The higher bit is set if the cell value is null or the smaller set if it is empty.
+A ``null`` cell means that this column doesn't have a value in the current row. An empty cell means that the value exists but is empty in a way (e.g., if the data type is ``text`` or `blob`, this indicates it has no bytes and a zero length in it). Note that for rows, clustering cells are never ``null``. But this encoding is also used for range tombstone markers that can contain only a prefix of clustering cells with others being treated as ``null`` in this case.
+The number of clustering blocks is not stored in the data file as it can be easily deduced from the schema.
+
+The resulting integer is then stored as ``varint clustering_block_header``. Next, the cells from the current batch are serialised using simple cells serialisation which is described below.
+
+Note that we don't store the number of clustering cells as we take this information from table schema.
+
+Sizes
+-----
+
+After the clustering blocks, the size of the serialised row is calculated and stored as a `varint`. This is the number of bytes between the byte after the last clustering block (inclusive) and the `flags` byte of the next `unfiltered` (exclusive) or the end of the file.
+
+Next `varint` is the size of the previous unfiltered (not necessarily a row, can be a range tombstone marker), supposedly stored to allow backwards traversal.
+
+Row Content
+-----------
+
+After the sizes, next goes the ``liveness_info`` which is defined as:
+
+.. code:: cpp
+
+ struct liveness_info {
+ varint delta_timestamp;
+ optional<varint> delta_ttl;
+ optional<varint> delta_local_deletion_time;
+ };
+
+
+It is present if ``HAS_TIMESTAMP`` flag is set. This liveness information is what allows us to distinguish between a dead row (it has no live cells and its primary key liveness info is empty) and a live row but where all non-PK columns are null (it has no live cells, but its primary key liveness is not empty). Please note that the liveness info only applies to the primary key columns and has no impact on the row content.
+In a way, ``liveness_info`` is a less hacky successor to CQL row marker used in 2.x data format.
+
+In liveness_info, as well as in some other places, timestamps, TTLs and deletion time values are stored as `varint`s using delta encoding. But an astute reader may ask a reasonable question: "What are the base values these deltas are taken from?". It turns out that a Memtable maintains aggregated statistics about all the information put into it and tracks the minimal timestamp, TTL and local deletion time values across all the records. These values are used as bases for delta encoding when the Memtable is flushed onto the disk. The values themselves are stored in `-Statistics.db` file and deserialised from there before the data file is read. For more details, refer to `EncodingStats.java`_ and `Memtable.java`_,
+
+.. _`EncodingStats.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/EncodingStats.java
+
+.. _`Memtable.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Memtable.java#L232
+
+
+If the TTL information was included in the modification statement, the ``HAS_TTL`` flag is set. In this case, both TTL and local deletion time values are stored as ``varints`` using deltas taken from the corresponding minimal values from Memtable stats.
+
+For dead row markers or expired liveness info, a special value -1 of TTL is set.
+
+If the row is deleted, `HAS_DELETION` flag is set. In this case, ``deletion_time`` is delta-encoded as follows:
+
+.. code:: cpp
+
+ struct delta_deletion_time {
+ varint delta_marked_for_delete_at;
+ varint delta_local_deletion_time;
+ };
+
+
+Note that the order here is different from partition header: in ``partition_header``, ``local_deletion_time`` is serialised first and then followed by ``marked_for_delete_at``. Here, delta-encoded ``marked_for_delete_at`` precedes delta-encoded ``local_deletion_time``.
+
+Shadowable Tombstones
+---------------------
+
+Cassandra only maintains up to one tombstone for a row. In case if it is shadowable, Cassandra sets the corresponding HAS_SHADOWABLE_DELETION_CASSANDRA flag.
+
+It turns out that this approach is imperfect and there are known issues with the current shadowable deletions support in Cassandra (see https://issues.apache.org/jira/browse/CASSANDRA-13826 for details).
+To address those, Scylla maintains a separate shadowable tombstone in addition to the regular one. That means a row can have up to two tombstones in Scylla-written SSTables. If the second tombstone is present, the Scylla-specific extended flag HAS_SHADOWABLE_DELETION_SCYLLA is set.
+
+Note that Cassandra does not know this flag and would consider those files invalid. This is deemed to be safe to do because shadowable tombstones can only appear in Materialized Views tables and those are not supposed to be ever exported and imported between Scylla and Cassandra.
+
+Missing Columns Encoding
+------------------------
+
+Reference:
+
+`Columns.java, serializeSubset`_
+
+.. _`Columns.java, serializeSubset`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/Columns.java#L444
+
+
+Next, if `HAS_ALL_COLUMNS` flag is **not** set, the `missing_columns` field contains information about which columns are _missing_. Note that the `HAS_ALL_COLUMNS` flag doesn't necessarily mean that the row has all the columns from the table schema definition. Each Memtable keeps track of filled columns on updates so when serialised into SSTables, the columns of a particular row are compared against the superset of filled columns in the Memtable. For example, if your table has 5 non-clustering columns ('a' through 'e'), all the records in the current Memtable have only some of ('a', 'b', 'c') filled and the current row has all 'a', 'b' and 'c', it will have the `HAS_ALL_COLUMNS` flag set even though it doesn't have columns 'd' and 'e'. This information (the list of all filled columns) is also stored in `-Statistics.db`.
+
+We have a _superset_ of columns, which is a list of all non-PK columns in the table, and a _current set of columns, which is a list of columns filled within this row. The encoding procedure is optimised towards small column sets (<64 columns) and employs slightly more complex encoding for larger sets.
+When the superset columns count is < 64, a 64-bit integer is used as a bitmap with its bits set for **missing** columns and stored as a single `varint`.
+
+For larger supersets, the delta between the superset columns count and the current row columns count is written as the first `varint`.
+The procedure then differs based on whether the number of columns in the row is less than half of the size of the superset or not.
+If `columns.count() < superset.count() / 2`, the **present** columns indices are written as `varints`, otherwise the **missing** columns indices are written. The logic is clear - we just write whatever appears to be less in count.
+
+Although the field is named `missing_columns`, one can see from the algorithm described above that in some cases the values stored are indices of present columns, not missing ones. This may be a bit confusing, but it helps to reason about it in the following way: whatever is stored can be used to get the list of missing columns.
+
+As of today, Scylla treats the whole set of columns as a superset regardless of whether all columns are ever filled or not. `See for details`_.
+
+.. _`See for details`: https://github.com/scylladb/scylla/issues/3901
+
+Lastly, all the cells of the current row are encoded.
+
+Cells
+-----
+
+References:
+
+* `BufferCell.java, Serializer.serialize`_
+
+* `UnfilteredSerializer, writeComplexColumn`_
+
+.. _`BufferCell.java, Serializer.serialize`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/BufferCell.java#L236
+
+.. _`UnfilteredSerializer, writeComplexColumn`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/UnfilteredSerializer.java#L204
+
+
+.. code:: cpp
+
+ struct cell {
+ };
+
+
+Any non-clustering column can be either "simple", which means it can only have a single cell associated to it in any row, or "complex", where an arbitrary number of cells can be associated. As of today, "complex" columns are those declared for non-frozen collections. All clustering columns are "simple" because non-frozen collections are allowed for non-PK columns only - if you remember, we said earlier that the cells in a clustering block are serialised using `simple_cell` serialisation.
+> Note that since we encode the information about filled columns, every cell is non-null by definition. They can still be empty though.
+
+A cell is recognised as simple or complex based the definition in the table schema for the column that owns this cell.
+
+Simple Cells
+------------
+
+A serialised simple sell looks like:
+
+.. code:: cpp
+
+ struct simple_cell
+ : cell {
+ byte flags;
+ optional<varint> delta_timestamp;
+ optional<varint> delta_local_deletion_time;
+ optional<varint> delta_ttl;
+ optional<cell_path> path; // only in cells nested into complex_cells
+ optional<struct cell_value> value;
+ };
+
+First, the `flags` byte is a bitwise-or of the following flags:
+
+.. code:: cpp
+
+ enum class cell_flags {
+ IS_DELETED_MASK = 0x01, // Whether the cell is a tombstone or not.
+ IS_EXPIRING_MASK = 0x02, // Whether the cell is expiring.
+ HAS_EMPTY_VALUE_MASK = 0x04, // Whether the cell has an empty value. This will be the case for a tombstone in particular.
+ USE_ROW_TIMESTAMP_MASK = 0x08, // Whether the cell has the same timestamp as the row this is a cell of.
+ USE_ROW_TTL_MASK = 0x10, // Whether the cell has the same TTL as the row this is a cell of.
+ };
+
+
+`IS_DELETED_MASK` and `IS_EXPIRING_MASK` flags are mutually exclusive for an obvious reason that the same cell can either be deleted or live but expiring.
+
+If `USE_ROW_TIMESTAMP_MASK` flag is **not** set, i.e., the cell timestamp differs from that of the row, the delta-encoded timestamp is stored as a `varint`.
+
+If the cell is a tombstone (`IS_DELETED_MASK` is set) or expiring (`IS_EXPIRING_MASK` is set) and its local deletion time and TTL differ from those of the row (`USE_ROW_TTL_MASK` is **not** set), cell delta-encoded local deletion time is stored as a `varint`.
+
+If the cell is expiring (`IS_EXPIRING_MASK` is set) and its TTL differs from that of the row (`USE_ROW_TTL_MASK` is **not** set), cell delta-encoded TTL is stored as a `varint`.
+
+A regular simple cell that belongs to a simple column doesn't have a `path` item. This one only appears in cells wrapped by a `complex_cell` (see below).
+
+Finally, if the cell value is not empty (`HAS_EMPTY_VALUE_MASK` is **not** set), it is serialised. It can be a fixed-width value (for fixed-width CQL data types like `int` or `boolean`) or a variable-width one (for CQL data types like `text` or `blob`). Those are encoded differently since we don't need to store the length of fixed-width values (it can be deduced from the table schema definition) but have to for variable-length cells.
+
+.. code:: cpp
+
+ struct cell_value {
+ optional<varint> length;
+ byte value[];
+ };
+
+
+Complex Cells
+-------------
+
+A complex cell acts as a kind of a container for multiple simple cells distinguished by so-called `cell_path`:
+
+.. code:: cpp
+
+ struct complex_cell
+ : cell {
+ optional<struct delta_deletion_time> complex_deletion_time;
+ varint items_count;
+ struct simple_cell[items_count];
+ };
+
+First, let's describe what a "complex deletion" means. A "complex deletion" is a deletion applied to all the items (or sub-cells) of a complex cell. For instance, for a collection, this corresponds to a full collection deletion. Note that if complex_deletion is absent, individual items (sub-cells) can still be deleted within a complex cell.
+
+The presence or absence of `complex_deletion_time` is determined by the `HAS_COMPLEX_DELETION` flag in row `flags`. Interestingly, this flag is set if any of row complex columns has a complex deletion, so in practice, it will be written for all the complex columns if at least one of them has been entirely deleted in the current row.
+
+Next, the number of items of the current complex cell (aka sub-cells) is stored as a `varint`.
+
+Lastly, we have the complex cell items serialised one by one. They, in fact, represent simple cells that have an additional `path` component that allows to distinguish them.
+
+.. code:: cpp
+
+ struct cell_path {
+ varint length;
+ byte value[length];
+ };
+
+As of today, the only implementation of the `cell_path` is the one for collections so it always has a single value which is:
+
+* an auto-generated `timeuuid` for lists
+* the current map key for maps
+* the actual value for sets (the `complex_cell_item.value` is empty in this case)
+
+Range Tombstone Marker
+----------------------
+
+References:
+
+* `RangeTombstoneMarker.java`_
+
+* `RangeTombstoneBoundMarker.java`_
+
+* `RangeTombstoneBoundaryMarker.java`_
+
+.. _`RangeTombstoneMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneMarker.java
+
+.. _`RangeTombstoneBoundMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneBoundMarker.java
+
+.. _`RangeTombstoneBoundaryMarker.java`: https://github.com/apache/cassandra/blob/cassandra-3.0/src/java/org/apache/cassandra/db/rows/RangeTombstoneBoundaryMarker.java
+
+In SSTables, we have a notion of range tombstones that represent tombstones that cover a slice/range of rows.
+Since 3.0, they are stored as pairs of range tombstone markers indicating its start and its end so that each tombstone corresponds to two ordered `unfiltered` objects or ``range_tombstone_marker`` type. This is done to simplify merging. The ordering of ``unfiltered`` by their clustering prefixes makes sure that a range tombstone start marker precedes any rows covered by the range and a range tombstone end marker goes after them.
+Given that, it becomes clear that as a reader advances through a data file, it has to maintain only up to one range tombstone deletion mark. If the deletion mark is filled, all the rows read are considered deleted until the corresponding end marker is met.
+
+Every range tombstone marker can be either a `range_tombstone_bound_marker`, which represents a single bound of a slice or a `range_tombstone_boundary_marker`, which represents a boundary between two adjacent range tombstones and notifies an "open end, closed start" type of bound. The latter makes for both disk space savings (requires 1 range tombstone marker instead of 2) and simplifies the merging logic of the database storage engine.
+
+.. code:: cpp
+
+ struct range_tombstone_marker {
+ byte flags = IS_MARKER;
+ byte kind_ordinal;
+ be16 bound_values_count;
+ struct clustering_block[] clustering_blocks;
+ varint marker_body_size;
+ varint prev_unfiltered_size;
+ };
+
+
+The first byte represents `flags` which for a range tombstone marker always contain a single ``IS_MARKER`` flag.
+Next byte is a slice bound kind ordinal:
+
+.. code:: cpp
+
+ enum class bound_kind : uint8_t {
+ EXCL_END_BOUND = 0,
+ INCL_START_BOUND = 1,
+ EXCL_END_INCL_START_BOUNDARY = 2,
+ STATIC_CLUSTERING = 3,
+ CLUSTERING = 4,
+ INCL_END_EXCL_START_BOUNDARY = 5,
+ INCL_END_BOUND = 6,
+ EXCL_START_BOUND = 7
+ };
+
+It can be one of {0, 1, 6, 7} for a ``range_tombstone_bound_marker`` and either 2 or 5 for a ``range_tombstone_boundary_marker``.
+Next, the two-byte integer value of the number of non-null columns in the clustering prefix is stored, followed by clustering blocks that are serialised in the exact same way as for rows.
+> For rows, the length of the clustering prefix is not stored as it is always full, meaning that all its clustering columns are non-`null`. For a range tombstone marker, however, the trailing columns can be `null` and so we need to know how many cells are encoded in the clustering blocks.
+
+After that, the size of the marker body is stored as a `varint`, followed by another `varint` that contains the size of the previous unfiltered (row or range tombstone marker).
+
+Next fields depend on whether this range tombstone marker is a bound or a boundary.
+
+.. code:: cpp
+
+ struct range_tombstone_bound_marker
+ : range_tombstone_marker {
+ struct delta_deletion_time deletion_time;
+ };
+
+ struct range_tombstone_boundary_marker
+ : range_tombstone_marker {
+ struct delta_deletion_time end_deletion_time;
+ struct delta_deletion_time start_deletion_time;
+ };
+
+For a bound marker, it stores its delta-encoded deletion time, and for boundary marker, we store two delta-encoded deletion time structures, one for the end bound and another for the start bound within the boundary.
+
+Shadowable Deletion
+-------------------
+
+Initially, an extended `HAS_SHADOWABLE_DELETION` flag has been introduced in 3.0 format to solve a tricky problem described in [CASSANDRA-10261](https://issues.apache.org/jira/browse/CASSANDRA-10261). Later some other problems have been discovered ([CASSANDRA-11500](https://issues.apache.org/jira/browse/CASSANDRA-11500)) which led to a more generic approach that deprecated shadowable tombstones and used expired liveness info instead.
+
+As a result, this flag is not supposed to be written for new SSTables by Cassandra.
+Scylla tracks the presence of this flag and fails to load files that have it set.
+
+
+References
+----------
+
+* `Putting some structure in the storage engine <https://www.datastax.com/2015/12/storage-engine-30>`_ - An overview of the main features of the SSTables 3.0 format including some measurements of disk space savings compared to 2.x.
+
+* `Introduction To The Apache Cassandra 3.x Storage Engine <https://thelastpickle.com/blog/2016/03/04/introductiont-to-the-apache-cassandra-3-storage-engine.html>`_ - A detailed article on SSTables 3.0 data file format with lots of references to the relevant code parts. This article has a few inaccuracies like complex cells format but otherwise is a great read with a lot of useful details.
+
+* `About Deletes and Tombstones in Cassandra <http://thelastpickle.com/blog/2016/07/27/about-deletes-and-tombstones.html>`_ - An article that covers tombstones in SSTables 3.0 in a great detail.
+
+* `Overview of CASSANDRA-8099 changes <https://apache.googlesource.com/cassandra/+show/cassandra-3.0.0-rc2/guide_8099.md>`_ - An engineering description of changes in SSTables data format in Cassandra 3.0. Explains well a variety of higher-level concepts and sheds light on some lower-level implementation details.
+
+* There is hardly any documentation that would be more accurate and up-to-date than the actual `source code <https://github.com/apache/cassandra/tree/cassandra-3.0>`_.
+
+.. include:: /rst_include/apache-copyrights.rst
+
\ No newline at end of file
diff --git a/docs/architecture/sstable/sstable3/sstables-3-index.rst b/docs/architecture/sstable/sstable3/sstables-3-index.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-index.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-index.rst
@@ -0,0 +1,162 @@
+SSTables 3.0 Index File Format
+==============================
+
+.. versionadded:: 3.0
+
+The SSTables index file, together with the :doc:`SSTables summary file </architecture/sstable/sstable3/sstables-3-summary/>` , provides a way to efficiently locate a partition with a specific key or some position within a partition in the :doc:`SSTables data file</architecture/sstable/sstable3/sstables-3-data-file-format/>`.
+
+Broadly, the index file lists the keys in the data file in order, giving for each key its position in the data file. The summary file, which is held in memory, contains samples of these keys, pointing to their position in the index file. So to efficiently search for a specific key, we use the summary to find a (relatively short) range of positions in the index file which may hold this key, then read this range from the index file and look for the specific key. The details on how to further pinpoint specific columns inside very long partitions are explained below.
+
+The Index File Layout
+.....................
+
+Building Blocks
+---------------
+
+The :ref:`building blocks <sstables-3-building-blocks>` of the new index format are same as those of the new data format.
+This includes ``varints``, ``optional`` values and delta encoding.
+
+Description
+-----------
+
+The index file format changes in v3.0 from the :doc:`old format </architecture/sstable/sstable2/sstable-format>` are moderate compared to how significantly has changed the data file layout. Still, there are some new fields and entities that are worth a detailed look. Such fields are the ``offsets`` array added to ``index_entry`` and ``end_open_marker`` structure added to ``promoted_index_block``.
+
+The index file is a long sequence of entries:
+
+.. code:: cpp
+
+ struct index_file {
+ struct index_entry entries[];
+ };
+
+ struct index_entry {
+ be16 key_length;
+ char key[key_length];
+ varint position; // decoded into a 64-bit integer
+ varint promoted_index_length; // decoded into a 32-bit integer
+ byte promoted_index[promoted_index_length];
+ };
+
+Here, key is the SSTable partition key, and position is the position of that partition in the data file.
+
+For large partitions, finding a specific range of columns requires more than just starting position to be efficient. For those, the so-called promoted index is stored along. It samples partition at roughly ``column_index_size_in_kb`` (by default, 64 KB) blocks and gives the clustering prefixes range for each block.
+
+The reason for the strange name ``promoted index`` is that it originally started as a separately stored column index, until in `Cassandra 1.2`_, when it was "promoted" to live inside the SSTables index file, reducing the number of seeks required to find a given column from 3 to 2.
+
+.. _`Cassandra 1.2`: https://issues.apache.org/jira/browse/CASSANDRA-2319
+
+The ``promoted_index_length`` stores the number of bytes right after this field and up to the end of the current ``index_entry``. If ``promoted_index_length`` is 0, there is no promoted index for this entry and nothing follows it.
+
+The structure of promoted index (when ``promoted_index_length != 0``) is as follows:
+
+.. code:: cpp
+
+ struct promoted_index {
+ varint partition_header_length; //decoded into a 64-bit integer
+ struct deletion_time deletion_time;
+ varint promoted_index_blocks_count; // decoded into a 32-bit integer
+ struct promoted_index_block blocks[promoted_index_blocks_count];
+ be32 offsets[promoted_index_blocks_count];
+ }
+
+The first field, ``partition_header_length``, stores the length of serialized partition key, partition tombstone and static row, if present, in the data file. This allows to skip over the partition prefix straight to the first clustered row.
+
+
+
+The `deletion time` structure is described in :doc:`SSTables 3.0 data file format</architecture/sstable/sstable3/sstables-3-data-file-format/>` article. It is simply a copy of the partition ``deletion_time``, either live or a partition tombstone. We need this copy inside the index, because normally the deletion_time of a partition appears in its very beginning in the data file, but with the promoted index we intend to skip directly to the middle of a very large partition, so we don't want to also read the beginning of the partition just to read its partition tombstone.
+
+After deletion time mark, the number of promoted index blocks is stored as a `varint`. It can be zero for small partitions or >= 2 (apparently, it makes no sense to store a single promoted index block).
+
+Promoted Index Blocks
+---------------------
+
+The promoted index block looks like:
+
+.. code:: cpp
+
+ struct promoted_index_block {
+ struct clustering_prefix first_name;
+ struct clustering_prefix last_name;
+ varint offset;
+ varint delta_width;
+ byte end_open_marker_present;
+ optional<struct deletion_time> end_open_marker;
+ };
+
+Clustering Prefixes
+-------------------
+
+Here, ``first_name`` and ``last_name`` are the serialised prefixes of clustering columns marking the boundaries of the block. They are stored as follows:
+
+.. code:: cpp
+
+ struct clustering_prefix {
+ byte kind;
+ optional<be16> size;
+ struct clustering_block clustering_blocks[];
+ };
+
+The first byte, `kind`, stores the serialised ordinal of the value from the ``bound_kind`` enum (see :doc:`SSTables 3.0 data file format</architecture/sstable/sstable3/sstables-3-data-file-format/>`) for the enum definition).
+It can be either 4 (for `CLUSTERING`) when corresponds to a row or one of 0, 1 and 2 (for ``EXCL_END_BOUND``, ``INCL_START_BOUND`` or ``EXCL_END_INCL_START_BOUNDARY`` accordingly) for a range tombstone marker.
+
+The next field, ``size``, is only present for range tombstone markers, i.e., when ``kind != 4``. It contains the actual number of values in the clustering prefix (the prefix length). For rows, it is not needed as rows have all the clustering columns values (full clustering prefix) so the count is taken from the table schema definition.
+
+The sequence of clustering blocks is serialised in exactly the same way as clustering blocks in rows or range tombstone markers in data files. You can refer to the detailed description :ref:`here <sstables-3-building-blocks>`
+
+
+Other Promoted Index Blocks Fields
+----------------------------------
+
+The ``offset`` field stores the start of the block relative to the beginning of the current partition in the data file.
+
+The `width` field is a delta-encoded value representing the length of the current promoted index block in the index file. The size of promoted index blocks is a configurable value set through the ``column_index_size_in_kb`` option in the config file. It defaults to 64KB and this is the base value that `width` delta is taken from.
+
+As of today, the base value is not stored along in the index file and always equals 64KB == 65536.
+
+Note that since the actual promoted index block size can be configured to be less than 64K, it can so happen that delta-encoding width would result in a negative value. Because of that, the stored value should be treated as **signed**.
+
+The next byte after `width` called ``end_open_marker_present`` is effectively a `boolean` which tells us whether the following ``end_open_marker`` structure is serialised or not. If ``end_open_marker_present`` is 1, ``end_open_marker`` should be read.
+
+The ``end_open_marker`` structure is present in case if the end bound of the current promoted index block falls in between two range tombstone markers denoting a range.
+In other words, that means that the block of ``unfiltereds`` in the data file that corresponds to this promoted index block contains a range tombstone start marker but its counterpart (range tombstone end marker) lies somewhere past that block.
+It is set for a range tombstone marker of either the ``INCL_START_BOUND`` or the ``EXCL_END_INCL_START_BOUNDARY`` kind and contains the open bound deletion time.
+
+The ``end_open_marker`` has to do with how range tombstones are organised in SSTables 3.0. and is closely connected with the merging logic of storage engine code. That code expects all the data it reads from SSTables to come strictly ordered and it expects range tombstone markers to always come in pairs (the combined "boundary" type marker is just treated as two markers - an end marker for the previous RT followed immediately by a start marker for a new RT.
+So when a slice of data is being read, it may contain an end RT marker without the corresponding start RT marker. In order to properly handle this, reader code returns a start RT marker corresponding to the slice start bound with the deletion time taken from the ``end_open_marker`` structure see: SSTableIterator.java.handlePreSliceData_
+
+.. _SSTableIterator.java.handlePreSliceData: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/columniterator/SSTableIterator.java#L125
+
+The higher-level reason for this design is that C* 3.0 storage design aims to be as iterator-based as possible and as such doesn't re-arrange the data it reads (and without start RT marker, such re-arrangement would be due).
+
+Lastly, there is an `offsets` array which stores the offsets for all the promoted index blocks.
+Its size is the same as the value stored in ``promoted_index_blocks_count``. The first offset is always 0, and others are the offsets of corresponding promoted index blocks from the beginning of ``promoted_index.blocks``.
+
+It is possible to read those offsets (commonly referred to as "offsets map") directly without reading the entire promoted index. This, in turn, allows searching through the promoted index using binary search which results in O(log N) reads instead of O (N).
+
+References
+..........
+
+The following code parts in Cassandra deal with index serialisation/de-serialisation:
+
+* `ColumnIndex.java, buildRowIndex`_
+
+* `RowIndexEntry.java`_
+
+* `IndexInfo.java`_
+
+.. _`ColumnIndex.java, buildRowIndex`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/ColumnIndex.java
+
+.. _`IndexInfo.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/IndexInfo.java
+
+.. _`RowIndexEntry.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/RowIndexEntry.java
+
+
+Additional Information
+----------------------
+
+The offset map reduces the complexity of search in the promoted index from O(N) to O(log N) using the offsets map.
+There are some better alternatives that should further improve the performance of index-related operations using BTree-like structures. They are not released yet but planned for Cassandra 4. See `CASSANDRA-9754`_.
+
+.. _`CASSANDRA-9754`: https://issues.apache.org/jira/browse/CASSANDRA-9754
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-statistics.rst b/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-statistics.rst
@@ -0,0 +1,294 @@
+SSTables 3.0 Statistics File Format
+===================================
+
+.. versionadded:: 3.0
+
+This file stores metadata for SSTable. There are 4 types of metadata:
+
+1. **Validation metadata** - used to validate SSTable correctness.
+2. **Compaction metadata** - used for compaction.
+3. **Statistics** - some information about SSTable which is loaded into memory and used for faster reads/compactions.
+4. **Serialization header** - keeps information about SSTable schema.
+
+General structure
+.................
+
+The file is composed of two parts. First part is a table of content which allows quick access to a selected metadata. Second part is a sequence of metadata stored one after the other.
+Let's define array template that will be used in this document.
+
+.. code:: cpp
+
+ struct array<LengthType, ElementType> {
+ LengthType number_of_elements;
+ ElementType elements[number_of_elements];
+ }
+
+
+Table of content
+
+.. code:: cpp
+
+ using toc = array<be32<int32_t>, toc_entry>;
+
+ struct toc_entry {
+ // Type of metadata
+ // | Type | Integer representation |
+ // |----------------------|------------------------|
+ // | Validation metadata | 0 |
+ // | Compaction metadata | 1 |
+ // | Statistics | 2 |
+ // | Serialization header | 3 |
+ be32<int32_t> type;
+ // Offset, in the file, at which this metadata entry starts
+ be32<int32_t> offset;
+ }
+
+The toc array is sorted by the type field of its members.
+
+Validation metadata entry
+.........................
+
+.. code:: cpp
+
+ struct validation_metadata {
+ // Name of partitioner used to create this SSTable.
+ // Represented by UTF8 string encoded using modified UTF-8 encoding.
+ // You can read more about this encoding in:
+ // https://docs.oracle.com/javase/7/docs/api/java/io/DataInput.html#modified-utf-8
+ // https://docs.oracle.com/javase/7/docs/api/java/io/DataInput.html#readUTF()
+ Modified_UTF-8_String partitioner_name;
+ // The probability of false positive matches in the bloom filter for this SSTable
+ be64<double> bloom_filter_fp_chance;
+ }
+
+Compaction metadata entry
+.........................
+
+.. code:: cpp
+
+ // Serialized HyperLogLogPlus which can be used to estimate the number of partition keys in the SSTable.
+ // If this is not present then the same estimation can be computed using Summary file.
+ // Encoding is described in:
+ // https://github.com/addthis/stream-lib/blob/master/src/main/java/com/clearspring/analytics/stream/cardinality/HyperLogLogPlus.java
+ using compaction_metadata = array<be32<int32_t>, be8>;
+
+Statistics entry
+................
+
+This entry contains some parts of ``EstimatedHistogram``, ``StreamingHistogram`` and ``CommitLogPosition`` types. Let's have a look at them first.
+
+EstimatedHistogram
+------------------
+
+.. code:: cpp
+
+ // Each bucket represents values from (previous bucket offset, current offset].
+ // Offset for last bucket is +inf.
+ using estimated_histogram = array<be32<int32_t>, bucket>;
+
+ struct bucket {
+ // Offset of the previous bucket
+ // In the first bucket this is offset of the first bucket itself because there's no previous bucket.
+ // The offset of the first bucket is repeated in second bucket as well.
+ be64<int64_t> prev_bucket_offset;
+ // This bucket value
+ be64<int64_t> value;
+ }
+
+StreamingHistogram
+------------------
+
+.. code:: cpp
+
+ struct streaming_histogram {
+ // Maximum number of buckets this historgam can have
+ be32<int32_t> bucket_number_limit;
+ array<be32<int32_t>, bucket> buckets;
+ }
+
+ struct bucket {
+ // Offset of this bucket
+ be64<double> offset;
+ // Bucket value
+ be64<int64_t> value;
+ }
+
+CommitLogPosition
+-----------------
+
+.. code:: cpp
+
+ struct commit_log_position {
+ be64<int64_t> segment_id;
+ be32<int32_t> position_in_segment;
+ }
+
+
+Whole entry
+-----------
+
+.. code:: cpp
+
+ struct statistics {
+ // In bytes, uncompressed sizes of partitions
+ estimated_histogram partition_sizes;
+ // Number of cells per partition
+ estimated_histogram column_counts;
+ commit_log_position commit_log_upper_bound;
+ // Typically in microseconds since the unix epoch, although this is not enforced
+ be64<int64_t> min_timestamp;
+ // Typically in microseconds since the unix epoch, although this is not enforced
+ be64<int64_t> max_timestamp;
+ // In seconds since the unix epoch
+ be32<int32_t> min_local_deletion_time;
+ // In seconds since the unix epoch
+ be32<int32_t> max_local_deletion_time;
+ be32<int32_t> min_ttl;
+ be32<int32_t> max_ttl;
+ // compressed_size / uncompressed_size
+ be64<double> compression_rate;
+ // Histogram of cell tombstones.
+ // Keys are local deletion times of tombstones
+ streaming_histogram tombstones;
+ be32<int32_t> level;
+ // The difference, measured in milliseconds, between repair time and midnight, January 1, 1970 UTC
+ be64<int64_t> repaired_at;
+ // Minimum and Maximum clustering key prefixes present in the SSTable (valid since the "md" SSTable format).
+ // Note that:
+ // - Clustering rows always have the full clustering key.
+ // - Range tombstones may have a partial clustering key prefix.
+ // - Partition tombstones implicitly apply to the full, unbound clustering range.
+ // Therefore, an empty (min|max)_clustering_key denotes a respective unbound range,
+ // derived either from an open-ended range tombstone, or from a partition tombstone.
+ clustering_bound min_clustering_key;
+ clustering_bound max_clustering_key;
+ be8<bool> has_legacy_counters;
+ be64<int64_t> number_of_columns;
+ be64<int64_t> number_of_rows;
+
+ // Version MA of SSTable 3.x format ends here.
+ // It contains only one commit log position interval - [NONE = new CommitLogPosition(-1, 0), upper bound of commit log]
+
+ commit_log_position commit_log_lower_bound;
+
+ // Version MB of SSTable 3.x format ends here.
+ // It contains only one commit log position interval - [lower bound of commit log, upper bound of commit log].
+
+ array<be32<int32_t>, commit_log_interval> commit_log_intervals;
+ }
+
+ using clustering_bound = array<be32<int32_t>, clustering_column>;
+ using clustering_column = array<be16<uint16_t>, be8>;
+
+ struct commit_log_interval {
+ commit_log_position start;
+ commit_log_position end;
+ }
+
+
+Serialization header
+....................
+
+.. code:: cpp
+
+ struct serialization_header {
+ vint<uint64_t> min_timestamp;
+ vint<uint32_t> min_local_deletion_time;
+ vint<uint32_t> min_ttl;
+ // If partition key has one column then this is the type of this column.
+ // Otherwise, this is a CompositeType that contains types of all partition key columns.
+ type partition_key_type;
+ array<vint<uint32_t>, type> clustering_key_types;
+ columns static_columns;
+ columns regular_columns;
+ }
+
+ using columns = array<vint<uint32_t>, column>;
+
+ struct column {
+ array<vint<uint32_t>, be8> name;
+ type column_type;
+ }
+
+ // UTF-8 string
+ using type = array<vint<uint_32_t>, be8>;
+
+Type encoding
+-------------
+
+Type is just a byte buffer with an unsigned variant integer (32-bit) length. It is a UTF-8 string. All leading spaces, tabs and newlines are skipped. Null or empty string is a bytes type. First segment of non-blank characters should contain only alphanumerical characters and special chars like ``'-'``, ``'+'``, ``'.'``, ``'_'``, ``'&'``. This is the name of the type. If type name does not contain any '.' then it gets "org.apache.cassandra.db.marshal." prepended to itself. Then an "instance" static field is taken from this class. If the first non-blank character that follows type name is '(' then "getInstance" static method is invoked instead. Remaining string is passed to this method as a parameter. There are following types:
+
+======================= ============
+Type Parametrized
+======================= ============
+Ascii Type No
+----------------------- ------------
+Boolean Type No
+----------------------- ------------
+Bytes Type No
+----------------------- ------------
+Byte Type No
+----------------------- ------------
+ColumnToCollection Type Yes
+----------------------- ------------
+Composite Type Yes
+----------------------- ------------
+CounterColumn Type No
+----------------------- ------------
+Date Type No
+----------------------- ------------
+Decimal Type No
+----------------------- ------------
+Double Type No
+----------------------- ------------
+Duration Type No
+----------------------- ------------
+DynamicComposite Type Yes
+----------------------- ------------
+Empty Type No
+----------------------- ------------
+Float Type No
+----------------------- ------------
+Frozen Type Yes
+----------------------- ------------
+InetAddress Type No
+----------------------- ------------
+Int32 Type No
+----------------------- ------------
+Integer Type No
+----------------------- ------------
+LexicalUUID Type No
+----------------------- ------------
+List Type Yes
+----------------------- ------------
+Long Type No
+----------------------- ------------
+Map Type Yes
+----------------------- ------------
+PartitionerDefinedOrder Yes
+----------------------- ------------
+Reversed Type Yes
+----------------------- ------------
+Set Type Yes
+----------------------- ------------
+Short Type No
+----------------------- ------------
+SimpleDate Type No
+----------------------- ------------
+Timestamp Type No
+----------------------- ------------
+Time Type No
+----------------------- ------------
+TimeUUID Type No
+----------------------- ------------
+Tuple Type Yes
+----------------------- ------------
+User Type Yes
+----------------------- ------------
+UTF8 Type No
+----------------------- ------------
+UUID Type No
+======================= ============
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/architecture/sstable/sstable3/sstables-3-summary.rst b/docs/architecture/sstable/sstable3/sstables-3-summary.rst
--- a/docs/architecture/sstable/sstable3/sstables-3-summary.rst
+++ b/docs/architecture/sstable/sstable3/sstables-3-summary.rst
@@ -0,0 +1,110 @@
+SSTables 3.0 Summary File Format
+================================
+
+.. versionadded:: 3.0
+
+SSTables summary file contains samples of keys that are used for the first, coarse-grained, stage of search through the index. Every summary entry points to a sequence of index entries commonly referred to as an index page where the key looked for is located. So with the summary, it is possible to only read and search through a small part of the index.
+
+The summary file is meant to be read and stored entirely in memory, therefore it is aimed to be reasonably small. This incurs some trade-off between the size of the summary and the cardinality of an index page (number of index entries covered by it). The less the cardinality is, the better precision the initial lookup through summary gives, but this also tends to increase the size of the summary. The balance between the two is regulated by the sampling level which rules how many index entries should one summary entry cover.
+
+SSTables Summary File Layout
+............................
+
+The summary file format in SSTables 3.0 has minimal changes compared to the previous version of the format described here: :doc:`SSTable 2.0 format </architecture/sstable/sstable2/sstable-format/>`
+The only noticeable change is that in 3.0 the summary file does not store information about segment boundaries. See `CASSANDRA-8630`_ for more details about this change.
+
+.. _`CASSANDRA-8630`: https://issues.apache.org/jira/browse/CASSANDRA-8630
+
+Other than that, the data format remains the same. Note that, unlike data and index files, the summary file does not make use of variable-length integers:
+
+.. code:: cpp
+
+ struct summary {
+ struct summary_header header;
+ struct summary_entries_block summary_entries;
+ struct serialized_key first;
+ struct serialized_key last;
+ };
+
+
+Summary Header
+--------------
+
+First goes the summary `header` which is laid out as follows:
+
+.. code:: cpp
+
+ struct summary_header {
+ be32 min_index_interval;
+ be32 entries_count;
+ be64 summary_entries_size;
+ be32 sampling_level;
+ be32 size_at_full_sampling;
+ };
+
+
+The ``min_index_interval`` is a lower bound for the average number of partitions in between each index summary entry. A lower value means that more partitions will have an entry in the index summary when at the full sampling level.
+
+The ``entries_count`` is the number of `offsets` and ``entries`` in the ``summary_entries`` structure (see below).
+
+The ``summary_entries_size`` is the full size of the ``summary_entries`` structure (see below).
+
+The ``sampling_level`` is a value between 1 and ``BASE_SAMPLING_LEVEL`` (which equals to 128) that represents how many of the original index summary entries ``((1 / indexInterval) * numKeys)`` have been retained. Thus, this summary contains ``(samplingLevel / BASE_SAMPLING_LEVEL) * ((1 / indexInterval) * numKeys))`` entries.
+
+The ``size_at_full_sampling`` is the number of entries the Summary **would** have if the sampling level would be equal to ``min_index_interval``.
+
+Summary Entries
+---------------
+
+.. code:: cpp
+
+ struct summary_entries_block {
+ uint32 offsets[header.entries_count];
+ struct summary_entry entries[header.entries_count];
+ };
+
+
+The ``offsets`` array contains offsets of corresponding entries in the ``entries`` array below. The offsets are taken from the beginning of the ``summary_entries_block`` so ``offsets[0] == sizeof(uint32) * header.entries_count`` as the first entry begins right after the array of offsets.
+
+Note that ``offsets`` are written in the native order format although typically all the integers in SSTables files are written in big-endian. In Scylla, they are always written in little-endian order to allow interoperability with 1. Summary files written by Cassandra on the more common little-endian machines, and 2. Summary files written by Scylla on the rarer big-endian machines.
+
+Here is how a summary entry looks:
+
+.. code:: cpp
+
+ struct summary_entry {
+ byte key[]; // variable-length.
+ be64 position;
+ };
+
+
+Every ``summary_entry`` holds a `key` and a ``position`` of the index entry with that key in the index file.
+Note that ``summary_entry`` does not store key length but it can be deduced from the offsets. The length of the last ``summary_entry`` in the `entries` array can be calculated using its offset and ``header.summary_entries_size``.
+
+Keys
+----
+
+The last two entries in the ``summary`` structure are ``serialized_keys`` that look like:
+
+.. code:: cpp
+
+ struct serialized_key {
+ be32 size;
+ byte key[size];
+ };
+
+
+They store the first and the last keys in the index/data file.
+
+References
+
+* `IndexSummary.java`_
+
+* `SSTableReader.java, saveSummary`_
+
+.. _`IndexSummary.java`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/IndexSummary.java
+
+.. _`SSTableReader.java, saveSummary`: https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/io/sstable/format/SSTableReader.java
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/contribute.rst b/docs/contribute.rst
--- a/docs/contribute.rst
+++ b/docs/contribute.rst
@@ -0,0 +1,31 @@
+Contribute to Scylla
+====================
+
+Thank you for your interest in making Scylla better!
+We appreciate your help and look forward to welcoming you to the Scylla Community.
+There are two ways you can contribute:
+
+* Send a patch to the Scylla source code
+* Write documentation for Scylla Docs
+
+
+Contribute to Scylla's Source Code
+----------------------------------
+Scylla developers use patches and email to share and discuss changes.
+Setting up can take a little time, but once you have done it the first time, it’s easy.
+
+The basic steps are:
+
+* Join the Scylla community
+* Create a Git branch to work on
+* Commit your work with clear commit messages and sign-offs.
+* Send a PR or use ``git format-patch`` and ``git send-email`` to send to the list
+
+
+The entire process is `documented here <https://scylla.docs.scylladb.com/master/contribute/index>`_.
+
+Contribute to Scylla Docs
+-------------------------
+
+Each Scylla project has accompanying documentation. For information about contributing documentation to a specific Scylla project, refer to the README file for the individual project.
+For general information or to contribute to the Scylla Sphinx theme, read the `Contributor's Guide <https://sphinx-theme.scylladb.com/stable/contribute/>`_.
\ No newline at end of file
diff --git a/docs/faq.rst b/docs/faq.rst
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -0,0 +1,498 @@
+===========
+Scylla FAQ
+===========
+
+.. meta::
+ :title:
+ :description: Frequently Asked Questions about ScyllaDB
+ :keywords: questions, Scylla, ScyllaDB, DBaaS, FAQ, error, problem
+
+Performance
+-----------
+
+I’m not getting the level of performance I expected. What’s wrong?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Lower than expected performance can be a result of many factors, from HW (storage, CPU, network) to data modeling to the application layer.
+As a first step, make sure to have |mon_root| in place. Looking at the Scylla dashboard is the best way to look for bottlenecks.
+If you need our help, please follow :doc:`How to Report a Performance Problem </troubleshooting/report-scylla-problem/>` to share data securely.
+
+Scylla is using all of my memory! Why is that? What if the server runs out of memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla uses available memory to cache your data. Scylla knows how to dynamically manage memory for optimal performance; for example, if many clients connect to Scylla, it will evict some data from the cache to make room for these connections; when the connection count drops again, this memory is returned to the cache.
+
+Can I limit Scylla to use less CPU and memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The :code:`--smp` option (for instance, :code:`--smp 2`) will restrict Scylla to a smaller number of CPUs. It will still use 100 % of those CPUs, but at least won’t take your system out completely. An analogous option exists for memory: :code:`-m`.
+
+Do I ever need to disable the Scylla cache to use less memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+It is not possible to turn off the Scylla cache. But cache problems do not arise in normal operation. Scylla can use up to 50% of memory for cache, and will dynamically evict rows from the cache if they are too large. So the only possibility of getting an out of memory error is if a single row is bigger than 50% of the memory for a shard. This is (total_machine_memory / (number_of_lcores * 2)).
+
+For a 64GB machine with 16 cores and hyperthreading enabled, you have 2GB per shard, of which the cache can use 1GB per shard. With such large rows, you will have other problems. We recommend staying with rows that are less than a few megabytes maximum size.
+
+What are some of the techniques Scylla uses to achieve its performance?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla tries to utilize all available resources (processor cores, memory, storage, and networking) by always operating in parallel and never blocking. If Scylla needs to read a disk block, it initiates the read and immediately moves on to another task. Later, when the read completes Scylla resumes the original task from where it left off. By never blocking, a high degree of concurrency is achieved, allowing all resources to be utilized to their limit.
+Read more on Scylla Architecture:
+
+* `Scylla Technology <http://www.scylladb.com/product/technology/>`_
+* `Scylla Memory Management <http://www.scylladb.com/product/technology/memory-management/>`_
+
+I thought that Scylla's underlying `Seastar framework <https://github.com/scylladb/seastar>`_ uses one thread per core, but I see more than two threads per core. Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Seastar creates an extra thread per core for blocking syscalls (like :code:`open()`/ :code:`fsync()` / :code:`close()` ); this allows the Seastar reactor to continue executing while a blocking operation takes place. Those threads are usually idle, so they don’t contribute to significant context switching activity.
+
+I’m seeing X compaction running in parallel on a single Scylla node. Is it normal?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Yes, for more than one reason:
+
+* each shard (core) will run its compactions independently, often at the same time,
+* each table will run its compactions independently, often at the same time
+* depending on the compaction strategy, more than one compaction can run in parallel. For example in Sized Tier Compaction Strategy (STCS), large sstable compaction can take time, allowing smaller sstable to be compacted at the same time
+
+.. _faq-io:
+
+Setting io.conf configuration for HDD storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As part of the Scylla setup process, **iotune** runs a short benchmark of your storage. When completed, it generates the `/etc/scylla.d/io.conf` configuration file. Note that iotune has known issues benchmarking HDD storage.
+
+.. note:: This section is not relevant in 2.3
+
+Therefore, when using Scylla with HDD storage, it is recommended to use RAID0 on all of your available disks, and manually update the `io.conf` configuration file `max-io-request` parameter. This parameter sets the number of concurrent requests sent to the storage. The value for this parameter should be 3X (3 times) the number of your disks. For example, if you have 3 disks, you would set `max-io-request=9`.
+
+How many connections is it recommended to open from each Scylla client application?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As a rule of thumb, for Scylla's best performance, each client needs at least 1-3 connection per Scylla core.
+For example, a cluster with three nodes, each node with 16 cores, each client application should open 32 (2x16) connections to each Scylla node.
+
+Do I need to configure ``swap`` on a Scylla node?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, configuring ``swap`` on a Scylla node is recommended.
+``swap`` size should be set to either ``total_mem``/3 or 16GB - lower of the two.
+
+``total_mem`` is the total size of the nodes memory.
+
+For example:
+
+* If the node ``total_mem`` is 18GB ``swap`` size should be set to 6GB.
+
+* If the node ``total_mem`` is 240GB ``swap`` size should be set to 16GB.
+
+Swap can be set up in several ways. One way to set up swap is detailed in the KB Article :doc:`How to Set up a Swap Space </kb/set-up-swap>`.
+
+After upgrade from Scylla 2.1 and older, scylla_reactor_utilization metrics is at high percentage (high CPU utilization is observed). Why does this happen?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla 2.2 enables the compaction automatic controller which was not present prior to version 2.2. What this means is that in Scylla 2.1 (and earlier) the system waits for 4 SSTables to be present in the same tier before starting a compaction. In Scylla 2.2 (and later), compactions can be controlled to not impact the workload. This means that workloads which have been considered as backlog in Scylla 2.1 and earlier, in Scylla 2.2 and later are not.
+
+My query does not return any or some of the data? What happened?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you are using a time range in the query, refer to the solution in the troubleshooting document, :doc:`Time Range Queries Do Not Return Some or All of the Data </troubleshooting/time-zone>`.
+
+
+DESC SCHEMA shows that I am using many materialized views (MVs) when I know I only added Secondary Indexes (SI). Why are there MVs in my schema?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As SI is built ontop of MV, you can expect to see MV in your schema. There is nothing wrong with your system. More information on :doc:`Global Secondary Indexes </using-scylla/secondary-indexes>`.
+
+
+Using the Java driver SimpleStatements are slow. Why does this happen?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Java driver's `SimpleStatement <https://java-driver.docs.scylladb.com/stable/manual/statements/simple/>`_ is token unaware by default. This means that requests sent out will reach the Controller node before it is known which shard it's supposed to access. We suggest using `PreparedStatements <https://java-driver.docs.scylladb.com/stable/manual/statements/prepared/>`_ instead.
+
+Disk Space
+-----------
+
+.. _reclaim-space:
+
+Dropping a table does not reduce storage used by Scylla, how can I clean the disk from dropped tables?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+scylla.yaml includes an ``auto_snapshot`` parameter; when true (it is by default), Scylla creates a snapshot for a table just before dropping it, as a safety measure.
+You can find the snapshot in the ``snapshots`` directory, under the table SSTable. For example, for dropped table ``users`` in keyspace ``mykeyspace``:
+
+:code:`/var/lib/scylla/data/mykeyspace/users-bdba4e60f6d511e7a2ab000000000000/snapshots/1515678531438-users`
+
+
+As the snapshot take the same space as the dropped table, disk usage will remain the same.
+You can clean snapshots by using :doc:`nodetool clearsnapshot </operating-scylla/nodetool-commands/clearsnapshot>`. Read more on :doc:`snapshot and clearsnapshot </operating-scylla/procedures/backup-restore/delete-snapshot/>`
+
+Features
+--------
+Will Scylla have a certain feature in an upcoming release?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Roadmap <http://www.scylladb.com/technology/status/>`_ page for features scheduled for our GA release.
+
+I want to try out new features. How do I enable experimental mode?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You need to add the line :code:`experimental: true` to your :code:`scylla.yaml` file.
+
+1. Launch the file in a text editor: :code:`$ vi /etc/scylla/scylla.yaml`. (Alternately, on docker, it's :code:`$ docker exec -it your_node vi /etc/scylla/scylla.yaml`);
+2. Add the line :code:`experimental: true`;
+3. Save the file and exit.
+4. Stop and restart the node.
+
+ On RedHat Enterprise Linux, CentOS or Ubuntu:
+
+ :code:`$ sudo systemctl restart scylla-server`
+
+ On Docker:
+
+ :code:`$ docker stop <your_node> && docker start <your_node>`
+
+ Alternately, starting from Scylla 2.0, you can start Scylla for Docker with the :code:`experimental` flag as follows:
+
+ :code:`$ docker run --name <your_node> -d scylladb/scylla --experimental 1`
+
+You should now be able to use the experimental features available in your version of Scylla.
+
+How do I check the current version of Scylla that I am running?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* On a regular system or VM (running Ubuntu, CentOS, or RedHat Enterprise): :code:`$ scylla --version`
+
+Check the :doc:`Operating System Support Guide </getting-started/os-support>` for a list of supported operating systems and versions.
+
+* On a docker node: :code:`$ docker exec -it Node_Z scylla --version`
+
+
+Is Scylla Apache Cassandra compatible? Is API / interface X compatible?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Cassandra Compatibility <http://www.scylladb.com/technology/status/#cassandra-compatibility>`_ section for compatibility matrix.
+
+Which version(s) of Apache Cassandra is Scylla compatible with? Will Scylla be compatible with future Cassandra versions?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the `Cassandra Compatibility <http://www.scylladb.com/technology/status/#cassandra-compatibility>`_ section for current and future Apache Cassandra release compatibility.
+
+
+I am upgrading my nodes to a version that uses a newer SSTable format, when will the nodes start using the new SSTable format?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :doc:`new "mc" SSTable format</architecture/sstable/sstable3/index>` is supported in Scylla 3.0 and later.
+Scylla only starts using the newer format when every node in the cluster is capable to generate it.
+Therefore, only when all nodes in the cluster are upgraded the new format is used.
+
+
+What if I get an error when trying to use cqlsh DESCRIBE commands?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Apache Cassandra 4.0 includes breaking changes in the DESCRIBE command by moving its implementation from the client (cqlsh)
+to the server. As a result, using DESCRIBE in cqlsh from Cassandra 4.0 package with Scylla will result in an error. As a remedy,
+you can do one of the following:
+
+* Use Scylla cqlsh:
+
+ * On Linux, you can install the ``scylla-tools`` package from the official ScyllaDB repository on GitHub.
+ The package contains cqlsh and other Apache Cassandra compatible tools for Scylla.
+ * On Linux, Windows, or Mac, you can run a Scylla container.
+* Downgrade your cqlsh to a version based on Cassandra 3.x, which supports DESCRIBE commands.
+
+.. note::
+ The Scylla roadmap includes moving DESCRIBE to server side, similarly to Cassandra 4.0. See https://github.com/scylladb/scylla/issues/9571 for information about progress.
+
+Ubuntu
+------
+
+.. _faq-check-update-kernel:
+
+Check and update Ubuntu 14.04 kernel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Running Scylla on Ubuntu 14.04 requires kernel 3.15 or later
+
+* To check your kernel version: :code:`$ uname -a`
+* If your kernel is older than 3.15 then:
+
+ * Check for available kernels: :code:`$ sudo apt-cache search linux-image`
+ * Install: :code:`$ sudo apt-get install linux-image-your_version_choice`, for example *linux-image-3.16.0*
+ * restart: :code:`$ sudo reboot now`
+
+Docker
+-------
+
+What if I get an error when connecting an application to a ScyllaDB cluster in Docker?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Connectivity problems may occur if you are trying to connect to the ScyllaDB nodes with their Docker internal IP addresses.
+
+If you need to reach your nodes from outside the internal Docker network, you must expose the appropriate ports to the Docker host.
+See `Error connecting Java Spring application to ScyllaDB Cluster in Docker <https://stackoverflow.com/questions/72165195/error-connecting-java-spring-application-to-scylladb-cluster-in-docker>`_ for more information and an example.
+
+
+Installation
+------------
+Can I install Scylla on an Apache Cassandra server?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scylla comes with its own version of the Apache Cassandra client tools, in the package :code:`scylla-tools`. Trying to install it on a server with Cassandra already installed may result in something like:
+
+.. code-block:: console
+
+ Unpacking scylla-tools (1.0.1-20160411.b9fe89b-ubuntu1) ...
+ dpkg: error processing archive /var/cache/apt/archives/scylla-tools_1.0.1-20160411.b9fe89b-ubuntu1_all.deb (--unpack):
+ trying to overwrite '/usr/bin/nodetool', which is also in package cassandra 2.1.4
+
+We recommend uninstalling Apache Cassandra before installing :code:`scylla-tools`.
+
+.. _faq-snitch-strategy:
+
+Which snitch or replication strategy should I use?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you are creating a production cluster or if your cluster is going to have more than one data center you need to use a **DC-aware** snitch, e.g. :code:`GossipingPropertyFileSnitch` or :code:`Ec2MultiRegionSnitch`. You will also need to use a **DC-aware** replication strategy, e.g. :code:`NetworkTopologyStrategy`.
+
+However, if you are going to create your first cluster or want to try something simple, if your cluster is going to have a single data center then you may use a :code:`SimpleSnitch` and then use a :code:`SimpleStrategy` for your keyspaces.
+
+Our general recommendation is to always use a :code:`NetworkTopologyStrategy` and use :code:`Ec2XXX` snitches on AWS based clusters and :code:`GossipingPropertyFileSnitch` in all other cases.
+
+A description of all snitch options we support may be found here: `Snitches <https://github.com/scylladb/scylla/wiki/Snitches>`_.
+
+Note: trying to mix a :code:`SimpleSnitch` with a :code:`DC-aware strategy` or a :code:`DC-aware snitch` with a :code:`SimpleStrategy` may cause your cluster not to work as intended therefore we **strongly discourage** these types of configurations in general.
+
+Not using a proper snitch-strategy combination may cause different types of errors.
+
+For instance:
+
+.. code-block:: console
+
+ Unavailable: code=1000 [Unavailable exception] message="Cannot achieve consistency level for cl LOCAL_ONE. Requires 1, alive 0" info={'required_replicas': 1, 'alive_replicas': 0, 'consistency': 'LOCAL_ONE'}
+
+If you see this error you should always check that you are not using a :code:`SimpleSnitch` in your cluster configuration in conjunction with some :code:`DC-aware replication strategy` for a keyspace of a table you are failing to query.
+
+When working with ``GossipingPropertyFileSnitch`` or ``Ec2MultiRegionSnitch`` you should edit the ``cassandra-rackdc.properties``
+
+For node using ``GossipingPropertyFileSnitch``, the file should look like the following:
+
+.. code-block:: cql
+
+ dc=asia_datacenter
+ rack=rack1
+ prefer_local= true
+
+When the node is the Asia data center, on rack1 and to minimize BW usage
+for inter-datacenter, use the prefer_local
+
+For ``Ec2MultiRegion`` the file should include the following information
+
+.. code-block:: cql
+
+ dc_suffix=my_dc
+
+This will create a suffix for the node location for example:
+
+.. code-block:: cql
+
+ us-east1_my_dc
+
+
+The problem may also arise if you are using some :code:`DC-aware snitch`, e.g. :code:`Ec2MultiRegionSnitch`, and a :code:`SimpleStrategy` in a multi-DC cluster.
+
+Please, make sure that both a snitch and a replication strategy of a keyspace are either both of a :code:`Simple` kind or both are :code:`DC-aware`.
+
+After that, if you are using a :code:`DC-aware` configuration, make sure that the replication strategy uses the proper data centers' names. Verify the data centers names in your cluster using a :code:`nodetool status` command.
+
+Can I change the replication factor (a keyspace) on a live cluster?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, but it will require running a full repair (or cleanup) to change the replica count of existing data:
+
+- :ref:`Alter <alter-keyspace-statement>` the replication factor for desired keyspace (using cqlsh for instance).
+- If you're reducing the replication factor, run ``nodetool cleanup <updated Keyspace>`` on the keyspace you modified to remove surplus replicated data.
+ Cleanup runs on a per-node basis.
+- If you're increasing the replication factor, refer to :doc:`How to Safely Increase the RF </kb/rf-increase>`
+- Note that you need to provide the keyspace namr. If you do not, the cleanup or repair operation runs on all keyspaces for the specific node.
+
+Why can't I set ``listen_address`` to listen to 0.0.0.0 (all my addresses)?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Scylla is a gossip-based distributed system and ``listen_address`` is the address a node tells other nodes to reach
+it at. Telling other nodes "contact me on any of my addresses" is a bad idea; if different nodes in the cluster pick
+different addresses for you, Bad Things happen.
+
+If you don't want to manually specify an IP to ``listen_address`` for each node in your cluster (understandable!), leave
+it blank and Scylla will use ``InetAddress.getLocalHost()`` to pick an address. Then it's up to you or your ops team
+to make things resolve correctly (``/etc/hosts/``, dns, etc).
+
+.. _faq-best-scenario-node-multi-availability-zone:
+
+What is the best scenario to add a node to a multi availability zone (AZ)?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If using three node cluster, with RF=3, each node located on a different availability zone (AZ).
+
+For example:
+
+.. code-block:: shell
+
+ Datacenter: DC1
+ Status=Up/Down
+ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 192.168.1.201 118.82 KB 256 33.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.202 111.82 KB 256 33.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.203 114.82 KB 256 33.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+
+All nodes holds 100% of the data.
+If needed to add a single node to the cluster (scale out), the cluster will become imbalance.
+Because the single additional node will split the tokens only with the existing node in the same AZ.
+
+.. Note::
+
+ This is only an example, if having more nodes or different RF the number of nodes may be different.
+
+
+The token distribution will be:
+
+.. code-block:: shell
+
+ AZ A1 node A: 100% of the data
+ AZ B1 node B: 100% of the data
+ AZ C1 node C: 50% of the data
+ AZ C1 node D: 50% of the data
+
+The solution is to add a node in each AZ.
+
+.. code-block:: shell
+
+ Datacenter: DC1
+ Status=Up/Down
+ State=Normal/Leaving/Joining/Moving
+ -- Address Load Tokens Owns (effective) Host ID Rack
+ UN 192.168.1.201 118.82 KB 256 16.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.202 111.82 KB 256 16.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.203 114.82 KB 256 16.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+ UN 192.168.1.204 118.82 KB 256 16.6% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c A1
+ UN 192.168.1.205 111.82 KB 256 16.1% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c B1
+ UN 192.168.1.206 114.82 KB 256 16.3% 8d5ed9f4-7764-4dbd-bad8-43fddce94b7c C1
+
+More info
+---------
+Where can I ask a question not covered here?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Two mailing lists.
+
+* `scylladb-dev <https://groups.google.com/d/forum/scylladb-dev>`_: Discuss the development of Scylla itself.
+* `scylladb-users <https://groups.google.com/d/forum/scylladb-users>`_: Discuss using Scylla and developing client applications.
+
+I deleted data from Scylla, but disk usage stays the same. Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Data you write to Scylla gets persisted to SSTables. Since SSTables are immutable, the data can't actually be removed
+when you perform a delete, instead, a marker (also called a "tombstone") is written to indicate the value's new status.
+Never fear though, on the first compaction that occurs between the data and the tombstone, the data will be expunged
+completely and the corresponding disk space recovered.
+
+What are seeds?
+^^^^^^^^^^^^^^^
+
+Seeds are used during startup to discover the cluster. They are referred by new nodes on bootstrap to learn about other nodes in the ring. When you add a new node to the cluster, you
+must specify one live seed to contact.
+
+In ScyllaDB versions earlier than Scylla Open Source 4.3 and Scylla Enterprise 2021.1, a seed node has an additional
+function: it assists with gossip convergence. See :doc:`Scylla Seed Nodes </kb/seed-nodes/>` for details.
+
+We recommend updating your ScyllaDB to version 4.3 or later (Open Source) or 2021.1 or later (Enterprise).
+
+Does single seed mean single point of failure?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ring can operate or boot without a seed; however, you will not be able to add new nodes to the cluster. It is recommended to configure multiple seeds in production systems.
+
+.. _faq-raid0-required:
+
+Is RAID0 required for Scylla? Why?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+No, it is not required, but it is highly recommended when using Scylla with more than one drive. Scylla requires one drive for its data file and one drive for commit log (can be the same). If you want to take advantage of more than one drive, the easiest way to do so is set RAID0 (striped) across all of them. If you choose, scylla_setup will setup RAID0 for you on your selected drive, as well as XFS file system (recommended).
+Similarly, Scylla AMI on EC2 will automatically mount all available SSD drives in RAID0.
+
+Should I use RAID for replications, such as RAID1, RAID4 or higher?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can, but it is not recommended. Scylla :doc:`clustering architecture </architecture/ringarchitecture/index/>` already provides data replication across nodes and DCs.
+Adding another layer of replication in each node is redundant, slows down I/O operation and reduces available storage.
+Want a higher level of replication?
+Increase the Replication Factor (RF) of :doc:`relevant Keyspaces </getting-started/ddl/>`.
+
+Can I use JBOD and not use RAID0?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:term:`JBOD` is not supported by Scylla.
+
+:abbr:`JBOD (Just a Bunch Of Disks)` may be a reasonable solution for Cassandra because it rebuilds nodes very slowly. As this is not an issue for Scylla, it's more efficient to use RAID.
+
+Explanation: There are two types of deployment when multiple disks exist. In the JBOD case, each disk is an isolated filesystem. I/O isn't stripped and thus performance can be slower than that of RAID. In addition, as the free space isn't shared, a single disk can be full while the others are available.
+
+The benefit of JBOD vs RAID is that it isolates failures to individual disk and not the entire node.
+However, Scylla rebuilds nodes quickly and thus it is not an issue when rebuilding an entire node.
+
+As a result, it is much more advantageous to use RAID with Scylla
+
+
+Is ``Nodetool Repair`` a Local (One Node) Operation or a Global (Full Cluster) Operation?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When running :doc:`nodetool repair </operating-scylla/nodetool-commands/repair/>` on a node, it performs a repair on every token range this node owns; this will also repair other nodes that share the same range.
+
+If you wish to repair the entire cluster, it is recommended to run ``nodetool repair -pr`` on each node in the cluster, sequentially, or use the :doc:`Scylla Manager </operating-scylla/manager/index/>`.
+
+
+How can I change the maximum number of IN restrictions?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can restrict the number of items in the IN clause with the following options:
+
+* ``--max-partition-key-restrictions-per-query`` - Specifies the maximum number of distinct partition keys restrictions per query. This limit places a bound
+ on the size of IN tuples, especially when multiple partition key columns have IN restrictions. The default is ``100``.
+* ``--max-clustering-key-restrictions-per-query`` - Specifies the maximum number of distinct clustering keys restrictions per query. This limit
+ places a bound on the size of IN tuples, especially when multiple clustering key columns have IN restrictions. The default is ``100``.
+
+.. warning::
+
+ We recommend that you use these options with caution. Changing the maximum number of IN restrictions to more than 100 may result in server instability.
+
+The options can be configured on the command line, passed with ``SCYLLA_ARGS`` in ``/etc/default/scylla-server`` or ``/etc/sysconfig/scylla-server``,
+or added to your ``scylla.yaml`` (see :doc:`Scylla Configuration<operating-scylla/admin>`).
+
+in-memory tables
+----------------
+
+Is MV and SI supported for use with in-memory tables? If so, how will it affect the total memory size limitation?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can make MV table an in-memory, as you would with every other table. It effects the total memory size allocation just like any other table. Make sure before you create any kind of in-memory table that its use case warrants the creation.
+
+Can Scylla Enterprise in-memory tables be used without having a mirror file on disk?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+No. In Scylla Enterprise 2018.1.7, in-memory tables are always persistent using an on-disk mirror file.
+
+What happens if we apply an ``ALTER`` CQL command to change a table from/to in memory?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It goes in and out of in-memory, as expected. This is :ref:`documented <change-a-table-to-an-in-memory-table>` in the Scylla Docs.
+
+Can I change the coredump mount point?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes, by edit ``sysctl.d``.
+
+Procedure
+
+1. Create ``/etc/sysctl.d/99-scylla-coredump.conf`` (this file exists by default in Scylla AMI).
+
+2. Open the ``99-scylla-coredump.conf`` file.
+
+3. Add the following line ``kernel.core_pattern=|/<path>/<coredump_directory> %p %u %g %s %t %e"``
+
+For example:
+
+.. code-block:: shell
+
+ kernel.core_pattern=|/home/centos/core/ %p %u %g %s %t %e"
+
+4. Run ``sysctl -p /etc/sysctl.d/99-scylla-coredump.conf``
+
+Do I need to run a tool like ``upgradesstables`` when moving to a new format?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike Apache Cassandra, Scylla does not ship with upgradesstables, a tool that converts SSTables to newer formats. When upgrading to a new table format, Scylla can still continue to read from the old format. Having this option, ensures a smoother transition and upgrade. New writes use the new format and reads will use both formats until the old tables are removed. If you want to purge all of the old SSTables in a single step, generate a compaction with :doc:`nodetool compact </operating-scylla/nodetool-commands/compact/>` follow by :doc:`nodetool cleanup </operating-scylla/nodetool-commands/cleanup/>` to remove no longer needed token ranges that belong to that node.
+
+
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/_common/note-io.rst b/docs/getting-started/_common/note-io.rst
--- a/docs/getting-started/_common/note-io.rst
+++ b/docs/getting-started/_common/note-io.rst
@@ -0,0 +1,10 @@
+.. note::
+
+ It's important to keep I/O scheduler configuration in sync on nodes with the same hardware.
+ That's why we recommend skipping running scylla_io_setup when provisioning a new node with exactly the same hardware setup as existing nodes in the cluster.
+
+ Instead, we recommend to copy the following files from an existing node to the new node after running scylla_setup and restart scylla-server service (if it is already running):
+ * /etc/scylla.d/io.conf
+ * /etc/scylla.d/io_properties.yaml
+
+ Using different I/O scheduler configuration may result in unnecessary bottlenecks.
diff --git a/docs/getting-started/_common/note-reclaim-space.rst b/docs/getting-started/_common/note-reclaim-space.rst
--- a/docs/getting-started/_common/note-reclaim-space.rst
+++ b/docs/getting-started/_common/note-reclaim-space.rst
@@ -0,0 +1,2 @@
+.. note:: By default, when a table or a keyspace is removed, a snapshot is taken so that you can restore it later. As a result, the disk space remains the same and is not immediately reclaimed.
+ Refer to :doc:`this article </troubleshooting/drop-table-space-up/>` or this :ref:`FAQ entry<reclaim-space>`.
\ No newline at end of file
diff --git a/docs/getting-started/_common/system-configuration-index.rst b/docs/getting-started/_common/system-configuration-index.rst
--- a/docs/getting-started/_common/system-configuration-index.rst
+++ b/docs/getting-started/_common/system-configuration-index.rst
@@ -0,0 +1,206 @@
+Configure Scylla
+================
+
+System configuration steps are performed automatically by the Scylla RPM and deb packages. For information on getting started with Scylla, see :doc:`Getting Started </getting-started/index>`.
+
+All Scylla AMIs and Docker images are pre-configured by a script with the following steps. This document is provided as a reference.
+
+.. _system-configuration-files-and-scripts:
+
+System Configuration Files and Scripts
+--------------------------------------
+Several system configuration settings should be applied. For ease of use, the necessary scripts and configuration files are provided. Files are under :code:`dist/common` and :code:`seastar/scripts` in the Scylla source code and installed in the appropriate system locations. (For information on Scylla’s own configuration file, see Scylla Configuration.)
+
+.. list-table:: System Configuration Files
+ :widths: 50 50
+ :header-rows: 1
+
+ * - File Name
+ - Description
+ * - scylla.conf
+ - Remove system resource limits
+ * - scylla-server
+ - Server startup options
+ * - (written by ``scylla_coredump_setup``, below)
+ - Configure core dumps to use the ``scylla_save_coredump`` script
+
+Scylla Scripts
+--------------
+
+The following scripts are available for you to run for configuring Scylla. Some of these scripts are included in the scylla_setup script. This script is used for configuring Scylla the first time, or when the system hardware changes.
+
+
+.. list-table:: Scylla Setup Scripts
+ :widths: 40 60
+ :header-rows: 1
+
+ * - perftune.py
+ - Configures various system parameters in order to improve the Seastar application performance
+ * - scylla_bootparam_setup
+ - Sets the kernel options in the bootloader. In addition, it tunes Linux boot-time parameters for the node that Scylla is running on (e.g. huge page setup).
+ * - scylla_coredump_setup
+ - Sets up coredump facilities for Scylla. This may include uninstalling existing crash reporting software for compatibility reasons.
+ * - scylla_io_setup
+ - Benchmarks the disks and generates the io.conf and io_properties.yaml files.
+ * - scylla_ntp_setup
+ - Configures Network Time Protocol
+ * - scylla_prepare
+ - This script is run automatically every time Scylla starts and the machine needs to be tuned.
+ * - scylla_raid_setup
+ - Configures RAID and makes an XFS filesystem.
+ * - scylla_save_coredump
+ - Compresses a core dump file (Ubuntu only)
+ * - scylla_setup
+ - Sets up the Scylla configuration. Many of these scripts are included in the setup script.
+ * - scylla_stop
+ - Resets network mode if running in virtio or DPDK mode.
+ * - scylla_swap_setup
+ - Configures a swap space on the host.
+ * - scylla_sysconfig_setup
+ - Rewrites the /etc/sysconfig/scylla file.
+
+
+.. list-table:: Scylla Scripts (Not included with Scylla-Setup)
+ :widths: 40 60
+ :header-rows: 1
+
+ * - Script Name
+ - Description
+ * - node_health_check
+ - Gathers metrics and information on the node, checking that the node is configured correctly.
+ * - scylla-blocktune
+ - Tunes the filesystem and block layer (e.g. block size I/O scheduler configuration) for Scylla.
+ * - scylla_cpuscaling_setup
+ - Configures the CPU frequency scaling (IOW, puts the CPU in "performance" mode, instead of the slower "powersave" mode).
+ * - scylla_cpuset_setup
+ - Configures which CPUs the Scylla server threads run on.
+ * - scylla_fstrim
+ - Runs ``fstrim``, which cleans up unused blocks of data from your SSD storage device. It runs automatically if you run scylla_fstrim_set up (see below).
+ * - scylla_fstrim_setup
+ - Configures a job so that ``fstrim`` runs automatically.
+ * - scylla-housekeeping
+ - Checks if there are new versions of Scylla available, and also shares some telemetry information for us to keep track of what versions are installed on the field.
+ * - scylla_rsyslog_setup
+ - Configures the "rsyslog" service, which is used to send logs to a remote server.
+ * - scylla_selinux_setup
+ - Disables SELinux for Scylla.
+
+.. _note-io:
+
+.. include:: /getting-started/_common/note-io.rst
+
+Bootloader Settings
+-------------------
+If Scylla is installed on an Amazon AMI, the bootloader should provide the :code:`clocksource=tsc` and :code:`tsc=reliable` options. This enables an accurate, high-resolution `Time Stamp Counter (TSC) <https://software.intel.com/en-us/blogs/2013/06/20/eliminate-the-dreaded-clocksource-is-unstable-message-switch-to-tsc-for-a-stable>`_ for setting the system time.
+
+This configuration is provided in the file :code:`/usr/lib/scylla/scylla_bootparam_setup`.
+
+Remove Crash Reporting Software
+-------------------------------
+Remove the :code:`apport-noui` or :code:`abrt` packages if present, and set up a location and file name pattern for core dumps.
+
+This configuration is provided in the file :code:`/usr/lib/scylla/scylla_bootparam_setup`.
+
+Set Up Network Time Synchronization
+-----------------------------------
+It is highly recommended to enforce time synchronization between Scylla servers.
+
+Run :code:`ntpstat` on all nodes to check that system time is synchronized. If you are running in a virtualized environment and your system time is set on the host, you may not need to run NTP on the guest. Check the documentation for your platform.
+
+If you have your own time servers shared with an application using Scylla, use the same NTP configuration as for your application servers. The script :code:`/usr/lib/scylla/scylla_ntp_setup` provides sensible defaults, using Amazon NTP servers if installed on the Amazon cloud, and other pool NTP servers otherwise.
+
+Set Up RAID and Filesystem
+--------------------------
+Setting the file system to XFS is the most important and mandatory for production. Scylla will significantly slow down without it.
+
+The script :code:`/usr/lib/scylla/scylla_raid_setup` performs the necessary RAID configuration and XFS filesystem creation for Scylla.
+
+Arguments to the script are
+
+* :code:`-d` specify disks for RAID
+* :code:`-r` MD device name for RAID
+* :code:`-u` update /etc/fstab for RAID
+
+On the Scylla AMI, the RAID configuration is handled automatically in the :code:`/usr/lib/scylla/scylla_prepare script`.
+
+CPU Pinning
+-----------
+
+When installing Scylla, it is highly recommended to use the :doc:`scylla_setup </getting-started/system-configuration>` script.
+Scylla should not share CPUs with any CPU consuming process. In addition, when running Scylla on AWS, we recommend pinning all NIC IRQs to CPU0 (due to the same reason). As a result, Scylla should be prevented from running on CPU0 and its hyper-threading siblings. To verify that Scylla is pinning CPU0, use the command below:
+If the node has four or fewer CPUs, don't use this option.
+
+To verify:
+
+.. code-block:: shell
+
+ cat /etc/scylla.d/cpuset.conf
+
+
+Example output:
+
+.. code-block:: shell
+
+ --cpuset `1-15,17-31`
+
+Networking
+----------
+On AWS:
+^^^^^^^
+1. Prevent irqbalance from moving your NICs’ IRQs.
+2. Bind all NICs’ HW queues to CPU0:
+
+.. code-block:: shell
+
+ for irq in `cat /proc/interrupts | grep <networking iface name> | cut -d":" -f1`
+ do echo "Binding IRQ $irq to CPU0" echo 1 > /proc/irq/$irq/smp_affinity done
+
+3. Enable RPS and bind RPS queues to CPUs other than CPU0 and its hyper-threading siblings.
+4. Enable XPS and distribute all XPS queues among all available CPUs.
+
+The `posix_net_conf.sh <https://github.com/scylladb/seastar/blob/master/scripts/posix_net_conf.sh>`_ script does all of the above.*
+
+On Bare Metal Setups with Multi-Queue NICs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+1. Prevent irqbalance from moving your NICs IRQs.
+2. Bind each NIC’s IRQ to a separate CPU.
+3. Enable XPS exactly the same way as for AWS above.
+4. Set higher values for a listen() socket backlog and for unacknowledged pending connections backlog:
+
+.. code-block:: shell
+
+ echo 4096 > /proc/sys/net/core/somaxconn
+ echo 4096 > /proc/sys/net/ipv4/tcp_max_syn_backlog
+
+The `posix_net_conf.sh <https://github.com/scylladb/seastar/blob/master/scripts/posix_net_conf.sh>`_ script with the :code:`-mq` parameter does all of the above.
+
+Configuring Scylla
+------------------
+Configuration for Scylla itself is in the :ref:`Scylla Configuration <admin-scylla-configuration>` section of the administration guide.
+
+Development System Configuration
+--------------------------------
+*The following item is not required in production.*
+
+When working on DPDK support for Scylla, enable hugepages.
+
+.. code-block:: shell
+
+ NR_HUGEPAGES=128
+ mount -t hugetlbfs -o pagesize=2097152 none /mnt/huge
+ mount -t hugetlbfs -o pagesize=2097152 none /dev/hugepages/
+ for n in /sys/devices/system/node/node?; do
+ echo $NR_HUGEPAGES > $n/hugepages/hugepages-2048kB/nr_hugepages;
+ done
+
+Huge page configuration is written to :code:`/etc/sysconfig/scylla-server` by the script :code:`/usr/lib/scylla/sysconfig_setup`
+
+
+
+
+Related Topics
+--------------
+
+:doc:`System Limits </kb/system-limits>` - outlines the system limits which should be set or removed.
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/appendices.rst b/docs/getting-started/appendices.rst
--- a/docs/getting-started/appendices.rst
+++ b/docs/getting-started/appendices.rst
@@ -0,0 +1,317 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+Appendices
+----------
+
+.. include:: /rst_include/cql-version-index.rst
+
+.. _appendix-A:
+
+Appendix A: CQL Keywords
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+CQL distinguishes between *reserved* and *non-reserved* keywords.
+Reserved keywords cannot be used as an identifier. They are truly reserved
+for the language (but one can enclose a reserved keyword by
+double-quotes to use it as an identifier). Non-reserved keywords, however,
+only have a specific meaning in a certain context but can be used as
+identifiers otherwise. The only *raison d’être* of these non-reserved
+keywords is convenience: some keyword are non-reserved when it was
+always easy for the parser to decide whether they were used as keywords
+or not.
+
++--------------------+-------------+
+| Keyword | Reserved? |
++====================+=============+
+| ``ADD`` | yes |
++--------------------+-------------+
+| ``AGGREGATE`` | no |
++--------------------+-------------+
+| ``ALL`` | no |
++--------------------+-------------+
+| ``ALLOW`` | yes |
++--------------------+-------------+
+| ``ALTER`` | yes |
++--------------------+-------------+
+| ``AND`` | yes |
++--------------------+-------------+
+| ``APPLY`` | yes |
++--------------------+-------------+
+| ``AS`` | no |
++--------------------+-------------+
+| ``ASC`` | yes |
++--------------------+-------------+
+| ``ASCII`` | no |
++--------------------+-------------+
+| ``AUTHORIZE`` | yes |
++--------------------+-------------+
+| ``BATCH`` | yes |
++--------------------+-------------+
+| ``BEGIN`` | yes |
++--------------------+-------------+
+| ``BIGINT`` | no |
++--------------------+-------------+
+| ``BLOB`` | no |
++--------------------+-------------+
+| ``BOOLEAN`` | no |
++--------------------+-------------+
+| ``BY`` | yes |
++--------------------+-------------+
+| ``CALLED`` | no |
++--------------------+-------------+
+| ``CLUSTERING`` | no |
++--------------------+-------------+
+| ``COLUMNFAMILY`` | yes |
++--------------------+-------------+
+| ``COMPACT`` | no |
++--------------------+-------------+
+| ``CONTAINS`` | no |
++--------------------+-------------+
+| ``COUNT`` | no |
++--------------------+-------------+
+| ``COUNTER`` | no |
++--------------------+-------------+
+| ``CREATE`` | yes |
++--------------------+-------------+
+| ``CUSTOM`` | no |
++--------------------+-------------+
+| ``DATE`` | no |
++--------------------+-------------+
+| ``DECIMAL`` | no |
++--------------------+-------------+
+| ``DELETE`` | yes |
++--------------------+-------------+
+| ``DESC`` | yes |
++--------------------+-------------+
+| ``DESCRIBE`` | yes |
++--------------------+-------------+
+| ``DISTINCT`` | no |
++--------------------+-------------+
+| ``DOUBLE`` | no |
++--------------------+-------------+
+| ``DROP`` | yes |
++--------------------+-------------+
+| ``ENTRIES`` | yes |
++--------------------+-------------+
+| ``EXECUTE`` | yes |
++--------------------+-------------+
+| ``EXISTS`` | no |
++--------------------+-------------+
+| ``FILTERING`` | no |
++--------------------+-------------+
+| ``FINALFUNC`` | no |
++--------------------+-------------+
+| ``FLOAT`` | no |
++--------------------+-------------+
+| ``FROM`` | yes |
++--------------------+-------------+
+| ``FROZEN`` | no |
++--------------------+-------------+
+| ``FULL`` | yes |
++--------------------+-------------+
+| ``FUNCTION`` | no |
++--------------------+-------------+
+| ``FUNCTIONS`` | no |
++--------------------+-------------+
+| ``GRANT`` | yes |
++--------------------+-------------+
+| ``IF`` | yes |
++--------------------+-------------+
+| ``IN`` | yes |
++--------------------+-------------+
+| ``INDEX`` | yes |
++--------------------+-------------+
+| ``INET`` | no |
++--------------------+-------------+
+| ``INFINITY`` | yes |
++--------------------+-------------+
+| ``INITCOND`` | no |
++--------------------+-------------+
+| ``INPUT`` | no |
++--------------------+-------------+
+| ``INSERT`` | yes |
++--------------------+-------------+
+| ``INT`` | no |
++--------------------+-------------+
+| ``INTO`` | yes |
++--------------------+-------------+
+| ``JSON`` | no |
++--------------------+-------------+
+| ``KEY`` | no |
++--------------------+-------------+
+| ``KEYS`` | no |
++--------------------+-------------+
+| ``KEYSPACE`` | yes |
++--------------------+-------------+
+| ``KEYSPACES`` | no |
++--------------------+-------------+
+| ``LANGUAGE`` | no |
++--------------------+-------------+
+| ``LIMIT`` | yes |
++--------------------+-------------+
+| ``LIST`` | no |
++--------------------+-------------+
+| ``LOGIN`` | no |
++--------------------+-------------+
+| ``MAP`` | no |
++--------------------+-------------+
+| ``MODIFY`` | yes |
++--------------------+-------------+
+| ``NAN`` | yes |
++--------------------+-------------+
+| ``NOLOGIN`` | no |
++--------------------+-------------+
+| ``NORECURSIVE`` | yes |
++--------------------+-------------+
+| ``NOSUPERUSER`` | no |
++--------------------+-------------+
+| ``NOT`` | yes |
++--------------------+-------------+
+| ``NULL`` | yes |
++--------------------+-------------+
+| ``OF`` | yes |
++--------------------+-------------+
+| ``ON`` | yes |
++--------------------+-------------+
+| ``OPTIONS`` | no |
++--------------------+-------------+
+| ``OR`` | yes |
++--------------------+-------------+
+| ``ORDER`` | yes |
++--------------------+-------------+
+| ``PASSWORD`` | no |
++--------------------+-------------+
+| ``PERMISSION`` | no |
++--------------------+-------------+
+| ``PERMISSIONS`` | no |
++--------------------+-------------+
+| ``PRIMARY`` | yes |
++--------------------+-------------+
+| ``RENAME`` | yes |
++--------------------+-------------+
+| ``REPLACE`` | yes |
++--------------------+-------------+
+| ``RETURNS`` | no |
++--------------------+-------------+
+| ``REVOKE`` | yes |
++--------------------+-------------+
+| ``ROLE`` | no |
++--------------------+-------------+
+| ``ROLES`` | no |
++--------------------+-------------+
+| ``SCHEMA`` | yes |
++--------------------+-------------+
+| ``SELECT`` | yes |
++--------------------+-------------+
+| ``SET`` | yes |
++--------------------+-------------+
+| ``SFUNC`` | no |
++--------------------+-------------+
+| ``SMALLINT`` | no |
++--------------------+-------------+
+| ``STATIC`` | no |
++--------------------+-------------+
+| ``STORAGE`` | no |
++--------------------+-------------+
+| ``STYPE`` | no |
++--------------------+-------------+
+| ``SUPERUSER`` | no |
++--------------------+-------------+
+| ``TABLE`` | yes |
++--------------------+-------------+
+| ``TEXT`` | no |
++--------------------+-------------+
+| ``TIME`` | no |
++--------------------+-------------+
+| ``TIMESTAMP`` | no |
++--------------------+-------------+
+| ``TIMEUUID`` | no |
++--------------------+-------------+
+| ``TINYINT`` | no |
++--------------------+-------------+
+| ``TO`` | yes |
++--------------------+-------------+
+| ``TOKEN`` | yes |
++--------------------+-------------+
+| ``TRIGGER`` | no |
++--------------------+-------------+
+| ``TRUNCATE`` | yes |
++--------------------+-------------+
+| ``TTL`` | no |
++--------------------+-------------+
+| ``TUPLE`` | no |
++--------------------+-------------+
+| ``TYPE`` | no |
++--------------------+-------------+
+| ``UNLOGGED`` | yes |
++--------------------+-------------+
+| ``UPDATE`` | yes |
++--------------------+-------------+
+| ``USE`` | yes |
++--------------------+-------------+
+| ``USER`` | no |
++--------------------+-------------+
+| ``USERS`` | no |
++--------------------+-------------+
+| ``USING`` | yes |
++--------------------+-------------+
+| ``UUID`` | no |
++--------------------+-------------+
+| ``VALUES`` | no |
++--------------------+-------------+
+| ``VARCHAR`` | no |
++--------------------+-------------+
+| ``VARINT`` | no |
++--------------------+-------------+
+| ``WHERE`` | yes |
++--------------------+-------------+
+| ``WITH`` | yes |
++--------------------+-------------+
+| ``WRITETIME`` | no |
++--------------------+-------------+
+
+Appendix B: CQL Reserved Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following type names are not currently used by CQL but are reserved
+for potential future use. User-defined types may not use reserved type
+names as their name.
+
++-----------------+
+| type |
++=================+
+| ``bitstring`` |
++-----------------+
+| ``byte`` |
++-----------------+
+| ``complex`` |
++-----------------+
+| ``enum`` |
++-----------------+
+| ``interval`` |
++-----------------+
+| ``macaddr`` |
++-----------------+
+
+
+
+.. include:: /rst_include/apache-copyrights-index.rst
+.. include:: /rst_include/apache-cql-return-index.rst
diff --git a/docs/getting-started/checkmark-16.png b/docs/getting-started/checkmark-16.png
--- a/docs/getting-started/checkmark-16.png
+++ b/docs/getting-started/checkmark-16.png
null
diff --git a/docs/getting-started/compaction.rst b/docs/getting-started/compaction.rst
--- a/docs/getting-started/compaction.rst
+++ b/docs/getting-started/compaction.rst
@@ -0,0 +1,352 @@
+
+.. _compaction:
+
+Compaction
+----------
+
+
+This document describes the compaction strategy options available when creating a table. For more information about creating a table in Scylla, refer to the :ref:`CQL Reference <create-table-statement>`.
+
+By default, Scylla starts a compaction task whenever a new SSTable is written. Compaction merges several SSTables into a new SSTable, which contains only the live data from the input SSTables. Merging several sorted files to get a sorted result is an efficient process, and this is the main reason why SSTables are kept sorted.
+
+The following compaction strategies are supported by Scylla:
+
+* Size-tiered Compaction Strategy (`STCS`_)
+
+* Leveled Compaction Strategy (`LCS`_)
+
+* Incremental Compaction Strategy (`ICS`_)
+
+* Time-window Compaction Strategy (`TWCS`_)
+
+* Date-tiered Compaction Strategy (DTCS) - use `TWCS`_ instead
+
+This page concentrates on the parameters to use when creating a table with a compaction strategy. If you are unsure which strategy to use or want general information on the compaction strategies which are available to Scylla, refer to :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>`.
+
+Common options
+^^^^^^^^^^^^^^
+The following options are available for all compaction strategies.
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'compaction_strategy_name',
+ 'enabled' : (true | false),
+ 'tombstone_threshold' : ratio,
+ 'tombstone_compaction_interval' : sec}
+
+
+
+``class`` (default: SizeTieredCompactionStrategy)
+ Selects the compaction strategy.
+
+ It can be one of the following. If you are unsure which one to choose, refer to :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>` :
+
+ * SizeTieredCompactionStrategy
+ * TimeWindowCompactionStrategy
+ * LeveledCompactionStrategy
+
+
+=====
+
+``enabled`` (default: true)
+ Runs background compaction (known as “minor compaction”). Can be one of the following:
+
+ * true - runs minor compaction
+ * false - disable minor compaction
+
+=====
+
+``tombstone_threshold`` (default: 0.2)
+ The ratio (expressed as a decimal) of garbage-collectable tombstones compared to the data. When this threshold is exceeded on a specific table, a single SSTable compaction begins. Acceptable values are numbers in the range 0 -1.
+
+=====
+
+``tombstone_compaction_interval`` (default: 86400s (1 day))
+ An SSTable that is suitable for single SSTable compaction, according to tombstone_threshold will not be compacted if it is newer than tombstone_compaction_interval.
+
+=====
+
+.. _STCS:
+
+Size Tiered Compaction Strategy (STCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When using STCS, SSTables are put in different buckets depending on their size. When an SSTable is bucketed, the average size of the tables is compared to the new table as well as the high and low threshold levels.
+
+The database compares each SSTable size to the average of all SSTable sizes on the node. It calculates ``bucket_low * avg_bucket_size`` and ``bucket_high * avg_bucket_size`` and then compares the result with the average SSTable size. The conditions set for ``bucket_high`` and ``bucket_low`` dictate if successive tables will be added to the same bucket. When compaction begins it merges SSTables whose size in KB are within ``[average-size * bucket_low]`` and ``[average-size * bucket_high]``.
+
+Once the ``min_threashold`` is reached, minor compaction begins.
+
+.. _stcs-options:
+
+STCS options
+~~~~~~~~~~~~
+
+The following options only apply to SizeTieredCompactionStrategy:
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'SizeTieredCompactionStrategy',
+ 'bucket_high' : factor,
+ 'bucket_low' : factor,
+ 'min_sstable_size' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables}
+
+``bucket_high`` (default: 1.5)
+ A new SSTable is added to the bucket if the SSTable size is less than bucket_high * the average size of that bucket (and if the bucket_low condition also holds).
+
+ For example, if **'bucket_high = 1.5'** and the **SSTable size = 14MB**, does it belong to a bucket with an average size of 10MB?
+
+ Yes, because the **SSTable size = 14`**, which is **less** than **'bucket_high' * average bucket size = 15**.
+
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``bucket_low`` (default: 0.5)
+ A new SSTable is added to the bucket if the SSTable size is more than bucket_low* the average size of that bucket (and if the bucket_high condition also holds).
+
+ For example, if **'bucket_high = 0.5'** and the **SSTable size is 10MB**, does it belong to a bucket with an average size is 15MB?
+
+ Yes, because the **SSTable size = 10** which is **more** than **'bucket_low' * average bucket size = 7.5**.
+
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``min_sstable_size`` (default: 50)
+ All SSTables smaller than this number of bytes are put into the same bucket.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTables that need to belong to the same size bucket before compaction is triggered on that bucket.
+ If your SSTables are small, use *min_sstable_size* to define a size threshold (in bytes) below which all SSTables belong to one unique bucket.
+
+ .. note:: Enforcement of ``min_threshold`` is controlled by the ``compaction_enforce_min_threshold`` configuration option in the scylla.yaml configuration settings.
+ By default, ``compaction_enforce_min_threshold: false``, meaning the Size-Tiered Compaction Strategy will compact any bucket containing 2 or more SSTables.
+ Otherwise, if ``compaction_enforce_min_threshold: true``, the value of ``min_threshold`` is considered and only those buckets that contain at
+ least ``min_threshold`` SSTables will be compacted.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+
+
+.. _LCS:
+
+Leveled Compaction Strategy (LCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compaction class LeveledCompactionStrategy (LCS) creates SSTables of a fixed, relatively small size (160 MB by default) that are grouped into levels. Within each level, SSTables are guaranteed to be non-overlapping. Each level (L0, L1, L2 and so on) is ten times as large as the previous level.
+
+.. _lcs-options:
+
+LCS options
+~~~~~~~~~~~
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'LeveledCompactionStrategy',
+ 'sstable_size_in_mb' : int}
+
+``sstable_size_in_mb`` (default: 160)
+ This is the target size in megabytes, that will be used as the goal for an SSTable size following a compression.
+ Although SSTable sizes should be less or equal to sstable_size_in_mb, it is possible that compaction could produce a larger SSTable during compaction. This occurs when data for a given partition key is exceptionally large.
+
+=====
+
+.. _ICS:
+
+Incremental Compaction Strategy (ICS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. note:: ICS is only available for Scylla Enterprise customers
+
+When using ICS, SSTable runs are put in different buckets depending on their size.
+When an SSTable run is bucketed, the average size of the runs in the bucket is compared to the new run, as well as the ``bucket_high`` and ``bucket_low`` levels.
+
+
+The database compares each SSTable-run size to the average of all SSTable-run sizes on all buckets in the node.
+It calculates ``bucket_low * avg_bucket_size`` and ``bucket_high * avg_bucket_size`` and then compares the result with the ``average SSTable-run size``.
+The conditions set for ``bucket_high`` and ``bucket_low`` dictate if successive runs will be added to the same bucket.
+When compaction begins it merges SSTable runs whose size in KB are within ``[average-size * bucket_low]`` and ``[average-size * bucket_high]``.
+
+
+Once there are multiple runs in a bucket, minor compaction begins.
+The minimum number of SSTable runs that triggers minor compaction is either 2 or ``min_threshold``, if the ``compaction_enforce_min_threshold``
+configuration option is set in the scylla.yaml configuration file.
+
+.. _ics-options:
+
+ICS options
+~~~~~~~~~~~~
+
+The following options only apply to IncrementalCompactionStrategy:
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'IncrementalCompactionStrategy',
+ 'bucket_high' : factor,
+ 'bucket_low' : factor,
+ 'min_sstable_size' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables,
+ 'sstable_size_in_mb' : int,
+ 'space_amplification_goal' : double}
+
+=====
+
+``bucket_high`` (default: 1.5)
+ A new SSTable is added to the bucket if the SSTable size is **less than**
+ bucket_high * the average size of that bucket (and if the bucket_low condition also holds).
+ For example, if **'bucket_high = 1.5'** and the **SSTable size = 14MB**, does the SSTable belong to a bucket with an average size of 10MB?
+ Yes, because the **SSTable size = 14**, which is **less** than **'bucket_high' * average bucket size = 15**.
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``bucket_low`` (default: 0.5)
+ A new SSTable is added to the bucket if the SSTable size is **more than**
+ bucket_low * the average size of that bucket (and if the bucket_high condition also holds).
+ For example, if **'bucket_high = 0.5'** and the **SSTable size is 10MB**, does the SSTable belong to a bucket with an average size of 15MB?
+ Yes, because the **SSTable size = 10**, which is **more** than **'bucket_low' * average bucket size = 7.5**.
+ So, the SSTable will be added to the bucket, and the bucket’s average size will be recalculated.
+
+=====
+
+``min_sstable_size`` (default: 50)
+ All SSTables smaller than this number of megabytes are put into the same bucket.
+
+ Unlike Apache Cassandra, scylla uses **uncompressed** size when bucketing similar-sized tiers together.
+ Since compaction works on uncompressed data, SSTables containing similar amounts of data should be compacted together, even when they have different compression ratios.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTable runs that need to belong to the same size bucket before compaction is triggered on that bucket.
+
+ .. note:: Enforcement of ``min_threshold`` is controlled by the ``compaction_enforce_min_threshold`` configuration option in the scylla.yaml configuration settings.
+ By default, ``compaction_enforce_min_threshold=false``, meaning the Incremental Compaction Strategy will compact any bucket containing 2 or more SSTable runs.
+ Otherwise, if ``compaction_enforce_min_threshold=true``, the value of ``min_threshold`` is considered and only those buckets that contain at
+ least ``min_threshold`` SSTable runs will be compacted.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+=====
+
+``sstable_size_in_mb`` (default: 1000)
+ This is the target size in megabytes, that will be used as the goal for an SSTable size (fragment size) following a compression.
+
+.. _SAG:
+
+=====
+
+``space_amplification_goal`` (default: null)
+
+.. versionadded:: 2020.1.6 Scylla Enterprise
+
+ This is a threshold of the ratio of the sum of the sizes of the two largest tiers to the size of the largest tier,
+ above which ICS will automatically compact the second largest and largest tiers together to eliminate stale data that may have been overwritten, expired, or deleted.
+ The space_amplification_goal is given as a double-precision floating point number that must be greater than 1.0.
+
+ For example, if **'space_amplification_goal = 1.25'** and the largest tier holds **1000GB**,
+ when the second-largest tier accumulates SSTables with the total size of 250GB or more,
+ the ``space_amplification_goal`` threshold is crossed and all the SSTables in the largest and second-largest tiers will be compacted together.
+
+=====
+
+.. _TWCS:
+
+Time Window CompactionStrategy (TWCS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The basic concept is that TimeWindowCompactionStrategy will create 1 SSTable per file for a given time window.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+.. _twcs-options:
+
+TWCS options
+~~~~~~~~~~~~
+
+.. code-block:: cql
+
+ compaction = {
+ 'class' : 'TimeWindowCompactionStrategy',
+ 'compaction_window_unit' : string,
+ 'compaction_window_size' : int,
+ 'expired_sstable_check_frequency_seconds' : int,
+ 'min_threshold' : num_sstables,
+ 'max_threshold' : num_sstables}
+
+``compaction_window_unit`` (default: DAYS)
+ A time unit used to determine the window size which can be one of the following:
+
+ * ``'MINUTES'``
+
+ * ``'HOURS'``
+
+ * ``'DAYS'``
+
+=====
+
+``compaction_window_size`` (default: 1)
+ The number of units which will make up a window.
+
+=====
+
+``expired_sstable_check_frequency_seconds`` (default: 600)
+ Specifies (in seconds) how often Scylla will check for fully expired SSTables, which can be immediately dropped.
+
+=====
+
+``min_threshold`` (default: 4)
+ Minimum number of SSTables that need to belong to the same size bucket before compaction is triggered on that bucket.
+
+=====
+
+``max_threshold`` (default: 32)
+ Maximum number of SSTables that will be compacted together in one compaction step.
+
+=====
+
+See Also
+^^^^^^^^^
+
+* :doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+* :doc:`Compaction Strategies </architecture/compaction/compaction-strategies/>`
+
+* :doc:`Compaction Overview </kb/compaction>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
diff --git a/docs/getting-started/configure.rst b/docs/getting-started/configure.rst
--- a/docs/getting-started/configure.rst
+++ b/docs/getting-started/configure.rst
@@ -0,0 +1,23 @@
+Configure Scylla
+================
+
+.. raw:: html
+
+ <div class="panel callout radius animated">
+ <div class="row">
+ <div class="medium-3 columns">
+ <h5 id="getting-started">Configure Scylla</h5>
+ </div>
+ <div class="medium-9 columns">
+
+.. include:: /rst_include/configure-index.rst
+
+
+.. raw:: html
+
+ </div>
+ </div>
+ </div>
+
+
+
diff --git a/docs/getting-started/consistency-calculator.html b/docs/getting-started/consistency-calculator.html
--- a/docs/getting-started/consistency-calculator.html
+++ b/docs/getting-started/consistency-calculator.html
@@ -0,0 +1,105 @@
+ <style>
+ .calculator {
+ width: fit-content;
+ }
+ .form-inline {
+ display: flex;
+ flex-flow: row wrap;
+ }
+ .form-inline label {
+ margin: 5px 10px 5px 0;
+ }
+ .form-inline input {
+ padding: 10px;
+ margin: 5px 10px 5px 0;
+ }
+ </style>
+ <div class="calculator">
+ <form class="form-inline" action="">
+ <div class="input">
+ <label for="nodes">Nodes</label><input style="width: 8ch;" type="number" min="1" value="3" name="nodes" id="nodes">
+ </div>
+ <div class="input">
+ <label for="replication-factor">Replication factor</label><input style="width: 8ch;" min="1" value="3" type="number" name="replication-factor" id="replication-factor">
+ </div>
+ <div class="input">
+ <label for="read-consistency">Read consistency level</label><select name="read-consistency" id="read-consistency">
+ <option value="ONE">ONE</option>
+ <option value="TWO">TWO</option>
+ <option value="THREE">THREE</option>
+ <option value="QUORUM">QUORUM</option>
+ <option value="ALL">ALL</option>
+ </select>
+ </div>
+ <div class="input">
+ <label for="write-consistency">Write consistency level</label><select name="write-consistency" id="write-consistency">
+ <option value="ONE">ONE</option>
+ <option value="TWO">TWO</option>
+ <option value="THREE">THREE</option>
+ <option value="QUORUM">QUORUM</option>
+ <option value="ALL">ALL</option>
+ </select>
+ </div>
+ </form>
+ <div class="results"></div>
+ </div>
+
+ <script>
+ function consistency(c, rf) {
+ switch(c) {
+ case "ONE":
+ return 1;
+ case "TWO":
+ return 2;
+ case "THREE":
+ return 3;
+ case "QUORUM":
+ return Math.floor(rf / 2) + 1;
+ case "ALL":
+ return rf;
+ }
+ }
+
+ function calculate() {
+ const nodes = Number.parseInt(document.querySelector("#nodes").value);
+ const readConsistency = document.querySelector("#read-consistency").value;
+ const writeConsistency = document.querySelector("#write-consistency").value;
+ const replicationFactor = document.querySelector("#replication-factor").value;
+ const writeConsistencyN = consistency(writeConsistency, replicationFactor);
+ const readConsistencyN = consistency(readConsistency, replicationFactor);
+
+
+ const resultsDiv = document.querySelector(".results");
+
+ if (nodes < replicationFactor) {
+ resultsDiv.textContent = "Replication factor must be smaller or equal to the number of nodes";
+ resultsDiv.classList.add("warning", "admonition");
+ } else if (writeConsistencyN > replicationFactor || readConsistencyN > replicationFactor) {
+ resultsDiv.textContent = "Consistency level must be lower than replication factor";
+ resultsDiv.classList.add("warning", "admonition");
+ } else {
+ const msg = [];
+ if (writeConsistencyN + readConsistencyN > replicationFactor) {
+ msg.push("Your reads are <b>consistent</b>");
+ } else {
+ msg.push("Your reads are <b>eventually consistent</b>");
+ }
+ msg.push(`You can lose ${replicationFactor - readConsistencyN} nodes without failing reads`);
+ msg.push(`You can lose ${writeConsistencyN - 1} nodes without data loss`);
+ msg.push(`Each node holds ~ ${Math.round(replicationFactor / nodes * 100)}% of your data`);
+
+ resultsDiv.classList.remove("warning", "admonition");
+ resultsDiv.innerHTML = msg.join("<br/>");
+ }
+ }
+
+ document.querySelectorAll(".input input").forEach((element) => {
+ element.addEventListener("input", calculate);
+ })
+
+ document.querySelectorAll(".input select").forEach((element) => {
+ element.addEventListener("input", calculate);
+ })
+
+ calculate();
+ </script>
diff --git a/docs/getting-started/consistency.rst b/docs/getting-started/consistency.rst
--- a/docs/getting-started/consistency.rst
+++ b/docs/getting-started/consistency.rst
@@ -0,0 +1,128 @@
+==================
+Consistency Levels
+==================
+
+
+A :term:`Consistency Level (CL)` is a dynamic value which dictates the number of replicas (in a cluster) that must acknowledge a read or write operation in order for the coordinator node to determine the operation was successful.
+CLs can be used with any transaction including LWTs.
+
+This value is set by the client on a per operation basis. For the CQL Shell, the consistency level defaults to ONE for read and write operations.
+If there is a conflict in settings, the CQLSH setting supersedes a consistency level global setting.
+
+
+Syntax
+------
+.. code-block:: cql
+
+ CONSISTENCY <consistency level>
+
+Examples
+========
+
+Set CONSISTENCY to force the majority of the nodes to respond:
+
+.. code-block:: cql
+
+ CONSISTENCY QUORUM
+
+Set level to serial for LWT read requests:
+
+.. code-block:: cql
+
+ CONSISTENCY SERIAL
+
+Consistency level set to SERIAL.
+
+.. _consistency-levels-reference:
+
+Consistency Levels Reference
+============================
+
+The following table describes the different levels you can set.
+
+.. list-table::
+ :widths: 25 25 25 25
+ :header-rows: 1
+
+ * - Consistency Level
+ - Which Replicas Must Respond
+ - Consistency
+ - Availability
+ * - ANY (Write Only)
+ - Closest replica, as determined by the snitch. If all replica nodes are down, write succeeds after a :term:`hinted handoff`. Provides low latency, guarantees writes never fail.
+ - Lowest (WRITE)
+ - Highest (WRITE)
+ * - ONE
+ - The closest replica as determined by the :term:`Snitch`. Consistency requirements are not too strict.
+ - Lowest (READ)
+ - Highest (READ)
+ * - TWO
+ - The closest two replicas as determined by the Snitch.
+ -
+ -
+ * - THREE
+ - The closest three replicas as determined by the Snitch.
+ -
+ -
+ * - QUORUM
+ - A simple majority of all replicas across all datacenters. This CL allows for some level of failure
+ -
+ -
+ * - LOCAL_QUORUM
+ - Same as QUORUM, but confined to the same datacenter as the coordinator.
+ - Low in multi-data centers
+ -
+ * - ALL
+ - *All* replicas in the cluster
+ - Highest
+ - Lowest (may cause performance issues)
+ * - EACH_QUORUM (Write Only)
+ - A simple majority in each datacenter.
+ - Same across the datacenters.
+ -
+ * - LOCAL_ONE
+ - Same as ONE, but confined to the local datacenter.
+ -
+ -
+ * - SERIAL
+ - Returns results with the most recent data. Including uncommitted in-flight LWTs. Writes are not supported, but read transactions are supported.
+ - Linearizable
+ -
+ * - LOCAL_SERIAL
+ - Same as SERIAL, but confined to a local datacenter. Writes are not supported, but read transactions are supported.
+ - Linearizable for the local DC
+ -
+
+
+Display the Current CL in CQLSh
+-------------------------------
+
+To display your current CL in your CQLsh session, use the CONSISTENCY Command with no options.
+
+.. code-block:: cql
+
+ CONSISTENCY
+
+
+returns
+
+.. code-block:: cql
+
+ Current consistency level is ALL.
+
+
+Consistency level calculator
+----------------------------
+
+.. raw:: html
+ :file: consistency-calculator.html
+
+
+Additional Information
+----------------------
+
+* :doc:`Fault Tolerance </architecture/architecture-fault-tolerance/>`
+* :doc:`Cluster membership changes and LWT consistency </operating-scylla/procedures/cluster-management/membership-changes/>`
+* :ref:`Consistency Level Compatibility <consistency-level-read-and-write>`
+* :doc:`Consistency Quiz </kb/quiz-administrators/>`
+* Take a course on `Consistency Levels at Scylla University <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability/topic/consistency-level/>`_
diff --git a/docs/getting-started/cql.rst b/docs/getting-started/cql.rst
--- a/docs/getting-started/cql.rst
+++ b/docs/getting-started/cql.rst
@@ -0,0 +1,28 @@
+Cassandra Query Language (CQL)
+==============================
+
+.. toctree::
+ :hidden:
+
+ CQLSh the CQL shell <cqlsh>
+ Data Definition </getting-started/ddl>
+ Data Manipulation </getting-started/dml>
+ Expiring Data with Time to Live </getting-started/time-to-live>
+ Security </operating-scylla/security/index>
+ Data Types </getting-started/types>
+ Appendices </getting-started/appendices>
+ Definitions </getting-started/definitions>
+ Materialized Views </getting-started/mv>
+ Functions </getting-started/functions>
+ JSON </getting-started/json>
+ Secondary Indexes </getting-started/secondary-indexes>
+ Compaction </getting-started/compaction>
+ Consistency Levels </getting-started/consistency>
+ Reserved Keywords </getting-started/reserved-keywords>
+ Non-reserved Keywords </getting-started/non-reserved-keywords>
+
+.. include:: /rst_include/cql-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
+.. Operators </getting-started/operators>
diff --git a/docs/getting-started/cqlsh.rst b/docs/getting-started/cqlsh.rst
--- a/docs/getting-started/cqlsh.rst
+++ b/docs/getting-started/cqlsh.rst
@@ -0,0 +1,537 @@
+
+.. highlight:: none
+
+.. _cqlsh:
+
+CQLSh: the CQL shell
+--------------------
+
+cqlsh is a command line shell for interacting with Cassandra through CQL (the Cassandra Query Language). It is shipped
+with every Cassandra package and can be found in the bin/ directory alongside the Cassandra executable. cqlsh utilizes
+the Python native protocol driver and connects to the single node specified on the command line.
+
+
+Compatibility
+^^^^^^^^^^^^^
+
+cqlsh is compatible with Python 2.7.
+
+In general, a given version of cqlsh is only guaranteed to work with the version of Cassandra that it was released with.
+In some cases, cqlsh may work with older or newer versions of Cassandra, but this is not officially supported.
+
+
+Optional Dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+cqlsh ships with all essential dependencies. However, there are some optional dependencies that can be installed to
+improve the capabilities of cqlsh.
+
+pytz
+~~~~
+
+By default, cqlsh displays all timestamps with a UTC timezone. To support display of timestamps with another timezone,
+the `pytz <http://pytz.sourceforge.net/>`__ library must be installed. See the ``timezone`` option in cqlshrc_ for
+specifying a timezone to use.
+
+cython
+~~~~~~
+
+The performance of cqlsh's ``COPY`` operations can be improved by installing `cython <http://cython.org/>`__. This will
+compile the python modules that are central to the performance of ``COPY``.
+
+cqlshrc
+^^^^^^^
+
+
+The ``cqlshrc`` file holds configuration options for cqlsh. By default, this is in the user's home directory:
+
+``~/.cassandra/cqlsh``, but a custom location can be specified with the ``--cqlshrc`` option.
+
+Example config values and documentation can be found in the ``conf/cqlshrc.sample`` file of a tarball installation. You
+can also view the latest version of `cqlshrc online <https://github.com/scylladb/scylla-tools-java/blob/master/conf/cqlshrc.sample>`_.
+
+
+Command Line Options
+^^^^^^^^^^^^^^^^^^^^
+
+Usage:
+
+``cqlsh [options] [host [port]]``
+
+Options:
+
+``-C`` ``--color``
+ Force color output
+
+``--no-color``
+ Disable color output
+
+``--browser``
+ Specify the browser to use for displaying cqlsh help. This can be one of the `supported browser names
+ <https://docs.python.org/2/library/webbrowser.html>`__ (e.g. ``firefox``) or a browser path followed by ``%s`` (e.g.
+ ``/usr/bin/google-chrome-stable %s``).
+
+``--ssl``
+ Use SSL when connecting to Cassandra
+
+``-u`` ``--user``
+ Username to authenticate against Cassandra with
+
+``-p`` ``--password``
+ The password to authenticate against Cassandra with should
+ be used in conjunction with ``--user``
+
+``-k`` ``--keyspace``
+ Keyspace to authenticate to should be used in conjunction
+ with ``--user``
+
+``-f`` ``--file``
+ Execute commands from the given file, then exit
+
+``--debug``
+ Print additional debugging information
+
+``--encoding``
+ Specify a non-default encoding for output (defaults to UTF-8)
+
+``--cqlshrc``
+ Specify a non-default location for the ``cqlshrc`` file
+
+``-e`` ``--execute``
+ Execute the given statement, then exit
+
+``--connect-timeout``
+ Specify the connection timeout in seconds (defaults to 2s)
+
+``--request-timeout``
+ Specify the request timeout in seconds (defaults to 10s)
+
+``-t`` ``--tty``
+ Force tty mode (command prompt)
+
+
+Special Commands
+^^^^^^^^^^^^^^^^
+
+In addition to supporting regular CQL statements, cqlsh also supports a number of special commands that are not part of
+CQL. These are detailed below.
+
+.. _cqlsh-consistency:
+
+CONSISTENCY
+~~~~~~~~~~~
+
+`Usage`: ``CONSISTENCY <consistency level>``
+
+Sets the consistency level for operations to follow. Valid arguments include:
+
+.. code-block:: cql
+
+ - ANY
+ - ONE
+ - TWO
+ - THREE
+ - QUORUM
+ - ALL
+ - LOCAL_QUORUM
+ - LOCAL_ONE
+ - SERIAL
+ - LOCAL_SERIAL
+
+.. _cqlsh-serial-consistency:
+
+SERIAL CONSISTENCY
+~~~~~~~~~~~~~~~~~~
+
+`Usage`: ``SERIAL CONSISTENCY <consistency level>``
+
+Sets the serial consistency level for operations to follow. Valid arguments include:
+
+- ``SERIAL``
+- ``LOCAL_SERIAL``
+
+The serial consistency level is only used by conditional updates (``INSERT``, ``UPDATE``, and ``DELETE`` with an ``IF``
+condition). For those, the serial consistency level defines the consistency level of the serial phase (or “paxos” phase)
+while the normal consistency level defines the consistency for the “learn” phase, i.e. what type of reads will be
+guaranteed to see the update right away. For example, if a conditional write has a consistency level of ``QUORUM`` (and
+is successful), then a ``QUORUM`` read is guaranteed to see that write. However, if the regular consistency level of that
+write is ``ANY``, then only a read with a consistency level of ``SERIAL`` is guaranteed to see it (even a read with
+consistency ``ALL`` is not guaranteed to be enough).
+
+.. _cqlsh-show-version:
+
+SHOW VERSION
+~~~~~~~~~~~~
+This command is useful if you want to check which Cassandra version is compatible with your Scylla version.
+Note that the two standards are not 100% identical and this command is simply a comparison tool.
+
+If you want to display your current Scylla Version, refer to :ref:`Check your current version of Scylla <check-your-current-version-of-scylla>`.
+
+The display shows:
+
+* The cqlsh tool version that you're using
+* The Apache Cassandra version that your version of Scylla is most compatible with
+* The CQL protocol standard that your version of Scylla is most compatible with
+* The native protocol standard that your version of Scylla is most compatible with
+
+Example:
+
+.. code-block:: none
+
+ cqlsh> SHOW VERSION
+
+Returns:
+
+.. code-block:: none
+
+ [cqlsh 5.0.1 | Cassandra 3.0.8 | CQL spec 3.3.1 | Native protocol v4]
+
+.. _cqlsh-show-host:
+
+SHOW HOST
+~~~~~~~~~
+
+Prints the IP address and port of the Cassandra node that cqlsh is connected to in addition to the cluster name.
+
+Example:
+
+.. code-block:: none
+
+ cqlsh> SHOW HOST
+
+Returns:
+
+.. code-block:: none
+
+ Connected to Prod_Cluster at 192.0.0.1:9042.
+
+.. _cqlsh-show-session:
+
+SHOW SESSION
+~~~~~~~~~~~~
+
+Pretty prints a specific tracing session.
+
+`Usage`: ``SHOW SESSION <session id>``
+
+Example usage:
+
+
+.. code-block:: none
+
+ cqlsh> SHOW SESSION 95ac6470-327e-11e6-beca-dfb660d92ad8
+
+Returns:
+
+.. code-block:: none
+
+ Tracing session: 95ac6470-327e-11e6-beca-dfb660d92ad8
+
+ activity | timestamp | source | source_elapsed | client
+ -----------------------------------------------------------+----------------------------+-----------+----------------+-----------
+ Execute CQL3 query | 2016-06-14 17:23:13.979000 | 127.0.0.1 | 0 | 127.0.0.1
+ Parsing SELECT * FROM system.local; [SharedPool-Worker-1] | 2016-06-14 17:23:13.982000 | 127.0.0.1 | 3843 | 127.0.0.1
+ ...
+
+.. _cqlsh-source:
+
+SOURCE
+~~~~~~
+
+Reads the contents of a file and executes each line as a CQL statement or special cqlsh command.
+
+`Usage`: ``SOURCE <string filename>``
+
+Example usage::
+
+ cqlsh> SOURCE '/home/thobbs/commands.cql'
+
+.. _cqlsh-capture:
+
+CAPTURE
+~~~~~~~
+
+Begins capturing command output and appending it to a specified file. Output will not be shown at the console while it
+is captured.
+
+`Usage`::
+
+ CAPTURE '<file>';
+ CAPTURE OFF;
+ CAPTURE;
+
+That is, the path to the file to be appended to must be given inside a string literal. The path is interpreted relative
+to the current working directory. The tilde shorthand notation (``'~/mydir'``) is supported for referring to ``$HOME``.
+
+Only query result output is captured. Errors and output from cqlsh-only commands will still be shown in the cqlsh
+session.
+
+To stop capturing output and show it in the cqlsh session again, use ``CAPTURE OFF``.
+
+To inspect the current capture configuration, use ``CAPTURE`` with no arguments.
+
+.. _cqlsh-help:
+
+HELP
+~~~~
+
+Gives information about cqlsh commands. To see available topics, enter ``HELP`` without any arguments. To see help on a
+topic, use ``HELP <topic>``. Also, see the ``--browser`` argument for controlling what browser is used to display help.
+
+.. _cqlsh-tracing:
+
+TRACING
+~~~~~~~
+
+Enables or disables tracing for queries. When tracing is enabled, once a query completes, a trace of the events during
+the query will be printed.
+
+`Usage`::
+
+ TRACING ON
+ TRACING OFF
+
+.. _cqlsh-paging:
+
+PAGING
+~~~~~~
+
+Enables paging, disables paging, or sets the page size for read queries. When paging is enabled, only one page of data
+will be fetched at a time, and a prompt will appear to fetch the next page. Generally, it's a good idea to leave paging
+enabled in an interactive session to avoid fetching and printing large amounts of data at once.
+
+`Usage`::
+
+ PAGING ON
+ PAGING OFF
+ PAGING <page size in rows>
+
+.. _cqlsh-expand:
+
+EXPAND
+~~~~~~
+
+Enables or disables vertical printing of rows. Enabling ``EXPAND`` is useful when many columns are fetched, or the
+contents of a single column are large.
+
+`Usage`::
+
+ EXPAND ON
+ EXPAND OFF
+
+.. _cqlsh-login:
+
+LOGIN
+~~~~~
+
+Authenticate as a specified Cassandra user for the current session.
+
+`Usage`::
+
+ LOGIN <username> [<password>]
+
+.. _cqlsh-exit:
+
+EXIT
+~~~~
+
+Ends the current session and terminates the cqlsh process.
+
+`Usage`::
+
+ EXIT
+ QUIT
+
+.. _cqlsh-clear:
+
+CLEAR
+~~~~~~
+
+Clears the console.
+
+`Usage`::
+
+ CLEAR
+ CLS
+
+.. _cqlsh-describe:
+
+DESCRIBE
+~~~~~~~~
+
+Prints a description (typically a series of DDL statements) of a schema element or the cluster. This is useful for
+dumping all or portions of the schema.
+
+.. code-block:: cql
+
+ DESCRIBE CLUSTER
+ DESCRIBE SCHEMA
+ DESCRIBE KEYSPACES
+ DESCRIBE KEYSPACE <keyspace name>
+ DESCRIBE TABLES
+ DESCRIBE TABLE <table name>
+ DESCRIBE MATERIALIZED VIEW <view name>
+ DESCRIBE TYPES
+ DESCRIBE TYPE <type name>
+ DESCRIBE FUNCTIONS
+ DESCRIBE FUNCTION <function name>
+ DESCRIBE AGGREGATES
+ DESCRIBE AGGREGATE <aggregate function name>
+
+In any of the commands, ``DESC`` may be used in place of ``DESCRIBE``.
+
+The ``DESCRIBE CLUSTER`` command prints the cluster name and partitioner::
+
+
+ cqlsh> DESCRIBE CLUSTER
+
+ Cluster: Test Cluster
+ Partitioner: Murmur3Partitioner
+
+The ``DESCRIBE SCHEMA`` command prints the DDL statements needed to recreate the entire schema. This is especially
+useful for dumping the schema in order to clone a cluster or restore from a backup.
+
+.. _cqlsh-copy-to:
+
+COPY TO
+~~~~~~~
+
+Copies data from a table to a CSV file.
+
+.. code-block:: cql
+
+ COPY <table name> [(<column>, ...)] TO <file name> WITH <copy option> [AND <copy option> ...]
+
+If no columns are specified, all columns from the table will be copied to the CSV file. A subset of columns to copy may
+be specified by adding a comma-separated list of column names surrounded by parenthesis after the table name.
+
+
+The ``<file name>`` should be a string literal (with single quotes) representing a path to the destination file. The
+file name can also contain the special value ``STDOUT`` (without single quotes) print the CSV to STDOUT.
+
+See :ref:`shared-copy-options` for options that apply to both ``COPY TO`` and ``COPY FROM``.
+
+Options for COPY TO
+```````````````````
+
+``MAXREQUESTS``
+ The maximum number token ranges to fetch simultaneously. Defaults to 6.
+
+``PAGESIZE``
+ The number of rows to fetch in a single page. Defaults to 1000.
+
+``PAGETIMEOUT``
+ By default, the page timeout is 10 seconds per 1000 entries
+ in the page size or 10 seconds if pagesize is smaller.
+
+``BEGINTOKEN``, ``ENDTOKEN``
+ Token range to export. Defaults to exporting the full ring.
+
+``MAXOUTPUTSIZE``
+ The maximum size of the output file measured in number of lines;
+ beyond this maximum the output file will be split into segments.
+ -1 means unlimited, and is the default.
+
+``ENCODING``
+ The encoding used for characters. Defaults to ``utf8``.
+
+.. _cqlsh-copy-from:
+
+COPY FROM
+~~~~~~~~~
+Copies data from a CSV file to table.
+
+.. code-block:: cql
+
+ COPY <table name> [(<column>, ...)] FROM <file name> WITH <copy option> [AND <copy option> ...]
+
+If no columns are specified, all columns from the CSV file will be copied to the table. A subset
+of columns to copy may be specified by adding a comma-separated list of column names surrounded
+by parenthesis after the table name.
+
+The ``<file name>`` should be a string literal (with single quotes) representing a path to the
+source file. The file name can also contain the special value``STDIN`` (without single quotes)
+to read the CSV data from STDIN.
+
+See :ref:`shared-copy-options` for options that apply to both ``COPY TO`` and ``COPY FROM``.
+
+Options for COPY FROM
+`````````````````````
+
+``INGESTRATE``
+ The maximum number of rows to process per second. Defaults to 100000.
+
+``MAXROWS``
+ The maximum number of rows to import. -1 means unlimited, and is the default.
+
+``SKIPROWS``
+ A number of initial rows to skip. Defaults to 0.
+
+``SKIPCOLS``
+ A comma-separated list of column names to ignore. By default, no columns are skipped.
+
+``MAXPARSEERRORS``
+ The maximum global number of parsing errors to ignore. -1 means unlimited, and is the default.
+
+``MAXINSERTERRORS``
+ The maximum global number of insert errors to ignore. -1 means unlimited. The default is 1000.
+
+``ERRFILE`` =
+ A file to store all rows that could not be imported. By default, this is ``import_<ks>_<table>.err`` where ``<ks>`` is
+ your keyspace and ``<table>`` is your table name.
+
+``MAXBATCHSIZE``
+ The max number of rows inserted in a single batch. Defaults to 20.
+
+``MINBATCHSIZE``
+ The min number of rows inserted in a single batch. Defaults to 2.
+
+``CHUNKSIZE``
+ The number of rows that are passed to child worker processes from the main process at a time. Defaults to 1000.
+
+.. _shared-copy-options:
+
+Shared COPY Options
+```````````````````
+
+Options that are common to both ``COPY TO`` and ``COPY FROM``.
+
+``NULLVAL``
+ The string placeholder for null values. Defaults to ``null``.
+
+``HEADER``
+ For ``COPY TO``, controls whether the first line in the CSV output file will contain the column names. For COPY FROM,
+ specifies whether the first line in the CSV input file contains column names. Defaults to ``false``.
+
+``DECIMALSEP``
+ The character that is used as the decimal point separator. Defaults to ``.``.
+
+``THOUSANDSSEP``
+ The character that is used to separate thousands. Defaults to the empty string.
+
+``BOOLSTYlE``
+ The string literal format for boolean values. By default this is ``True, False``.
+
+``NUMPROCESSES``
+ The number of child worker processes to create for ``COPY`` tasks. Defaults to a max of 4 for ``COPY FROM`` and 16
+ for ``COPY TO``. However, at most (num_cores - 1), processes will be created.
+
+``MAXATTEMPTS``
+ The maximum number of failed attempts to fetch a range of data (when using ``COPY TO``) or insert a chunk of data
+ (when using ``COPY FROM``) before giving up. Defaults to 5.
+
+``REPORTFREQUENCY``
+ How often status updates are refreshed in seconds. By default, this is 0.25 seconds.
+
+``RATEFILE``
+ An optional file to export rate statistics to. By default, this is disabled and statistics are not exported to a file.
+
+See also:
+
+CQLSH `lesson <https://university.scylladb.com/courses/data-modeling/lessons/basic-data-modeling-2/topic/cql-cqlsh-and-basic-cql-syntax/>`_ on Scylla University
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+:doc:`Back </getting-started/index/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/ddl.rst b/docs/getting-started/ddl.rst
--- a/docs/getting-started/ddl.rst
+++ b/docs/getting-started/ddl.rst
@@ -0,0 +1,989 @@
+.. highlight:: cql
+
+Data Definition
+===============
+
+
+.. include:: /rst_include/cql-version-index.rst
+
+CQL stores data in *tables*, whose schema defines the layout of said data in the table, and those tables are grouped in
+*keyspaces*. A keyspace defines a number of options that apply to all the tables it contains, most prominently of
+which is the replication strategy used by the keyspace. An application can have only one keyspace. However, it is also possible to
+have multiple keyspaces in case your application has different replication requirements.
+
+This section describes the statements used to create, modify, and remove keyspaces and tables.
+
+:ref:`CREATE KEYSPACE <create-keyspace-statement>`
+
+.. _create-keyspace:
+
+:ref:`USE <use-statement>`
+
+.. _use:
+
+:ref:`ALTER KEYSPACE <alter-keyspace-statement>`
+
+.. _ALTER KEYSPACE:
+
+:ref:`DROP KEYSPACE <drop-keyspace-statement>`
+
+.. _DROP KEYSPACE:
+
+:ref:`CREATE TABLE <create-table-statement>`
+
+.. _CREATE TABLE:
+
+:ref:`ALTER TABLE <alter-table-statement>`
+
+.. _ALTER TABLE:
+
+:ref:`DROP TABLE <drop-table-statement>`
+
+.. _DROP TABLE:
+
+:ref:`TRUNCATE <truncate-statement>`
+
+.. _TRUNCATE:
+
+.. _data-definition:
+
+Common Definitions
+^^^^^^^^^^^^^^^^^^
+
+Keyspace and table names are defined by the following grammar:
+
+.. code-block:: cql
+
+ keyspace_name: `name`
+ table_name: [ `keyspace_name` '.' ] `name`
+ name: `unquoted_name` | `quoted_name`
+ unquoted_name: re('[a-zA-Z_0-9]{1, 48}')
+ quoted_name: '"' `unquoted_name` '"'
+
+Both keyspace and table names consist of only alphanumeric characters, cannot be empty, and are limited in
+size to 48 characters (that limit exists mostly to avoid filenames, which may include the keyspace and table name, to go
+over the limits of certain file systems). By default, keyspace and table names are case insensitive (``myTable`` is
+equivalent to ``mytable``), but case sensitivity can be forced by using double-quotes (``"myTable"`` is different from
+``mytable``).
+
+Further, a table is always part of a keyspace, and a table name can be provided fully-qualified by the keyspace it is
+part of. If it is not fully-qualified, the table is assumed to be in the *current* keyspace (see :ref:`USE statement
+<use-statement>`).
+
+Further, valid column names are simply defined as:
+
+.. code-block:: cql
+
+ column_name: `identifier`
+
+We also define the notion of statement options for use in the following section:
+
+.. code-block:: cql
+
+ options: `option` ( AND `option` )*
+ option: `identifier` '=' ( `identifier` | `constant` | `map_literal` )
+
+.. _create-keyspace-statement:
+
+In all cases, for creating keyspaces and tables, if you are using :doc:`Reserved Keywords </getting-started/reserved-keywords>`, enclose them in single or double-quotes.
+
+CREATE KEYSPACE
+^^^^^^^^^^^^^^^
+
+A keyspace is created using a ``CREATE KEYSPACE`` statement:
+
+.. code-block:: cql
+
+ create_keyspace_statement: CREATE KEYSPACE [ IF NOT EXISTS ] `keyspace_name` WITH `options`
+
+For example:
+
+.. code-block:: cql
+
+ CREATE KEYSPACE Excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1' : 1, 'DC2' : 3}
+ AND durable_writes = true;
+
+
+.. code-block:: cql
+
+ CREATE KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 3};
+
+
+The supported ``options`` are:
+
+=================== ========== =========== ========= ===================================================================
+name kind mandatory default description
+=================== ========== =========== ========= ===================================================================
+``replication`` *map* yes The replication strategy and options to use for the keyspace (see
+ details below).
+``durable_writes`` *simple* no true Whether to use the commit log for updates on this keyspace
+ (disable this option at your own risk!).
+=================== ========== =========== ========= ===================================================================
+
+The ``replication`` property is mandatory and must at least contains the ``'class'`` sub-option, which defines the
+replication strategy class to use. The rest of the sub-options depend on what replication
+strategy is used. By default, Scylla supports the following ``'class'``:
+
+.. _replication-strategy:
+
+SimpleStrategy
+~~~~~~~~~~~~~~~
+
+A simple strategy that defines a replication factor for data to be spread
+across the entire cluster. This is generally not a wise choice for production
+because it does not respect datacenter layouts and can lead to wildly varying
+query latency. For a production ready strategy, see *NetworkTopologyStrategy* . *SimpleStrategy* supports a single mandatory argument:
+
+========================= ====== ======= =============================================
+sub-option type since description
+========================= ====== ======= =============================================
+``'replication_factor'`` int all The number of replicas to store per range
+========================= ====== ======= =============================================
+
+.. note:: Using NetworkTopologyStrategy is recommended. Using SimpleStrategy will make it harder to add Data Center in the future.
+
+NetworkTopologyStrategy
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A production ready replication strategy that allows to set the replication
+factor independently for each data-center. The rest of the sub-options are
+key-value pairs where a key is a data-center name and its value is the
+associated replication factor. Options:
+
+===================================== ====== =============================================
+sub-option type description
+===================================== ====== =============================================
+``'<datacenter>'`` int The number of replicas to store per range in
+ the provided datacenter.
+``'replication_factor'`` int The number of replicas to use as a default
+ per datacenter if not specifically provided.
+ Note that this always defers to existing
+ definitions or explicit datacenter settings.
+ For example, to have three replicas per
+ datacenter, supply this with a value of 3.
+===================================== ====== =============================================
+
+Note that when ``ALTER`` ing keyspaces and supplying ``replication_factor``,
+auto-expansion will only *add* new datacenters for safety, it will not alter
+existing datacenters or remove any even if they are no longer in the cluster.
+If you want to remove datacenters while still supplying ``replication_factor``,
+explicitly zero out the datacenter you want to have zero replicas.
+
+An example of auto-expanding datacenters with two datacenters: ``DC1`` and ``DC2``::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3}
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3', 'DC2': '3'} AND durable_writes = true;
+
+
+An example of auto-expanding and overriding a datacenter::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3, 'DC2': 2}
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3', 'DC2': '2'} AND durable_writes = true;
+
+An example that excludes a datacenter while using ``replication_factor``::
+
+ CREATE KEYSPACE excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor' : 3, 'DC2': 0} ;
+
+ DESCRIBE KEYSPACE excalibur
+ CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3'} AND durable_writes = true;
+
+.. _use-statement:
+
+USE
+^^^
+
+The ``USE`` statement allows you to change the *current* keyspace (for the *connection* on which it is executed). Some objects in CQL are bound to a keyspace (tables, user-defined types, functions, ...), and the current keyspace is the
+default keyspace used when those objects are referred without a fully-qualified name (that is, without being prefixed a
+keyspace name). A ``USE`` statement simply takes the specified keyspace and uses the name as an argument for all future actions until this name is changed.
+
+.. code-block:: cql
+
+ use_statement: USE `keyspace_name`
+
+.. _alter-keyspace-statement:
+
+ALTER KEYSPACE
+^^^^^^^^^^^^^^
+
+An ``ALTER KEYSPACE`` statement lets you modify the options of a keyspace:
+
+.. code-block:: cql
+
+ alter_keyspace_statement: ALTER KEYSPACE `keyspace_name` WITH `options`
+
+For instance::
+
+ ALTER KEYSPACE Excelsior
+ WITH replication = { 'class' : 'NetworkTopologyStrategy', 'dc1' : 3, 'dc2' : 0};
+
+
+ ALTER KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4};
+
+
+
+The supported options are the same as :ref:`creating a keyspace <create-keyspace-statement>`.
+
+.. _drop-keyspace-statement:
+
+DROP KEYSPACE
+^^^^^^^^^^^^^
+
+Dropping a keyspace can be done using the ``DROP KEYSPACE`` statement:
+
+.. code-block:: cql
+
+ drop_keyspace_statement: DROP KEYSPACE [ IF EXISTS ] `keyspace_name`
+
+For instance::
+
+ DROP KEYSPACE Excelsior;
+
+Dropping a keyspace results in the immediate removal of that keyspace, including all the tables, UTD and
+functions in it, and all the data contained in those tables.
+
+.. include:: /getting-started/_common/note-reclaim-space.rst
+
+If the keyspace does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case the
+operation is a no-op.
+
+.. _create-table-statement:
+
+CREATE TABLE
+^^^^^^^^^^^^
+
+Creating a new table uses the ``CREATE TABLE`` statement:
+
+.. code-block:: cql
+
+ create_table_statement: CREATE TABLE [ IF NOT EXISTS ] `table_name`
+ : '('
+ : `column_definition`
+ : ( ',' `column_definition` )*
+ : [ ',' PRIMARY KEY '(' `primary_key` ')' ]
+ : ')' [ WITH `table_options` ]
+
+ column_definition: `column_name` `cql_type` [ STATIC ] [ PRIMARY KEY]
+
+ primary_key: `partition_key` [ ',' `clustering_columns` ]
+
+ partition_key: `column_name`
+ : | '(' `column_name` ( ',' `column_name` )* ')'
+
+ clustering_columns: `column_name` ( ',' `column_name` )*
+
+ table_options: COMPACT STORAGE [ AND `table_options` ]
+ : | CLUSTERING ORDER BY '(' `clustering_order` ')' [ AND `table_options` ]
+ : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'
+ : | caching '=' ' {'caching_options'}'
+ : | `options`
+
+ clustering_order: `column_name` (ASC | DESC) ( ',' `column_name` (ASC | DESC) )*
+
+For instance::
+
+ CREATE TABLE monkeySpecies (
+ species text PRIMARY KEY,
+ common_name text,
+ population varint,
+ average_size int
+ ) WITH comment='Important biological records'
+ AND read_repair_chance = 1.0;
+
+ CREATE TABLE timeline (
+ userid uuid,
+ posted_month int,
+ posted_time uuid,
+ body text,
+ posted_by text,
+ PRIMARY KEY (userid, posted_month, posted_time)
+ ) WITH compaction = { 'class' : 'LeveledCompactionStrategy' };
+
+ CREATE TABLE loads (
+ machine inet,
+ cpu int,
+ mtime timeuuid,
+ load float,
+ PRIMARY KEY ((machine, cpu), mtime)
+ ) WITH CLUSTERING ORDER BY (mtime DESC);
+
+ CREATE TABLE users_picture (
+ userid uuid,
+ pictureid uuid,
+ body text,
+ posted_by text,
+ PRIMARY KEY (userid, pictureid, posted_by)
+ ) WITH compression = {'sstable_compression': 'LZ4Compressor'};
+
+
+ CREATE TABLE data_atrest (
+ pk text PRIMARY KEY,
+ c0 int
+ ) WITH scylla_encryption_options = {
+ 'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
+ 'secret_key_strength' : 128,
+ 'key_provider': 'LocalFileSystemKeyProviderFactory',
+ 'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};
+
+ CREATE TABLE caching (
+ k int PRIMARY KEY,
+ v1 int,
+ v2 int,
+ ) WITH caching = {'enabled': 'true'};
+
+
+A CQL table has a name and is composed of a set of *rows*. Creating a table amounts to defining which :ref:`columns
+<column-definition>` the rows will be composed, which of those columns compose the :ref:`primary key <primary-key>`, as
+well as optional :ref:`options <create-table-options>` for the table.
+
+Attempting to create an already existing table will return an error unless the ``IF NOT EXISTS`` directive is used. If
+it is used, the statement will be a no-op if the table already exists.
+
+
+.. _column-definition:
+
+Column definitions
+~~~~~~~~~~~~~~~~~~
+
+Every row in a CQL table has a set of predefined columns defined at the time of the table creation (or added later
+using an :ref:`alter statement<alter-table-statement>`).
+
+A :token:`column_definition` is primarily comprised of the name of the column defined and its :ref:`type <data-types>`,
+which restricts which values are accepted for that column. Additionally, a column definition can have the following
+modifiers:
+
+``STATIC``
+ declares the column as being a :ref:`static column <static-columns>`.
+
+``PRIMARY KEY``
+ declares the column as being the sole component of the :ref:`primary key <primary-key>` of the table.
+
+.. _static-columns:
+
+Static columns
+``````````````
+Some columns can be declared as ``STATIC`` in a table definition. A column that is static will be “shared” by all the
+rows belonging to the same partition (having the same :ref:`partition key <partition-key>`). For instance::
+
+ CREATE TABLE t (
+ pk int,
+ t int,
+ v text,
+ s text static,
+ PRIMARY KEY (pk, t)
+ );
+
+ INSERT INTO t (pk, t, v, s) VALUES (0, 0, 'val0', 'static0');
+ INSERT INTO t (pk, t, v, s) VALUES (0, 1, 'val1', 'static1');
+
+ SELECT * FROM t;
+ pk | t | v | s
+ ----+---+--------+-----------
+ 0 | 0 | 'val0' | 'static1'
+ 0 | 1 | 'val1' | 'static1'
+
+As can be seen, the ``s`` value is the same (``static1``) for both of the rows in the partition (the partition key in
+that example being ``pk``, both rows are in that same partition): the 2nd insertion has overridden the value for ``s``.
+
+Static columns have the following restrictions:
+
+- tables with the ``COMPACT STORAGE`` option (see below) cannot use them.
+- a table without clustering columns cannot have static columns (in a table without clustering columns, every partition
+ has only one row, and so every column is inherently static).
+- only non ``PRIMARY KEY`` columns can be static.
+
+.. _primary-key:
+
+The Primary key
+~~~~~~~~~~~~~~~
+
+Within a table, a row is uniquely identified by its ``PRIMARY KEY``, and hence all tables **must** define a PRIMARY KEY
+(and only one). A ``PRIMARY KEY`` definition is composed of one or more of the columns defined in the table.
+Syntactically, the primary key is defined by the keywords ``PRIMARY KEY``, followed by a comma-separated list of the column
+names composing it within parenthesis. However, if the primary key has only one column, one can alternatively follow that
+column definition by the ``PRIMARY KEY`` keywords. The order of the columns in the primary key definition matter.
+
+A CQL primary key is composed of 2 parts:
+
+- the :ref:`partition key <partition-key>` part. It is the first component of the primary key definition. It can be a
+ single column or, using additional parenthesis, can be multiple columns. A table always has at least a partition key,
+ the smallest possible table definition is::
+
+ CREATE TABLE t (k text PRIMARY KEY);
+
+- the :ref:`clustering columns <clustering-columns>`. Those are the columns after the first component of the primary key
+ definition, and the order of those columns define the *clustering order*.
+
+Some examples of primary key definition are:
+
+- ``PRIMARY KEY (a)``: ``a`` is the partition key, and there are no clustering columns.
+- ``PRIMARY KEY (a, b, c)``: ``a`` is the partition key, and ``b`` and ``c`` are the clustering columns.
+- ``PRIMARY KEY ((a, b), c)``: ``a`` and ``b`` compose the partition key (this is often called a *composite* partition
+ key), and ``c`` is the clustering column.
+
+
+.. note:: A *null* value is not allowed as any partition-key or clustering-key column. A Null value is *not* the same as an empty string.
+
+.. _partition-key:
+
+The partition key
+`````````````````
+
+Within a table, CQL defines the notion of a *partition*. A partition is simply the set of rows that share the same value
+for their partition key. Note that if the partition key is composed of multiple columns, then rows belong to the same
+partition only when they have the same values for all those partition key columns. So, for instance, given the following table
+definition and content::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ d int,
+ PRIMARY KEY ((a, b), c, d)
+ );
+
+ SELECT * FROM t;
+ a | b | c | d
+ ---+---+---+---
+ 0 | 0 | 0 | 0 // row 1
+ 0 | 0 | 1 | 1 // row 2
+ 0 | 1 | 2 | 2 // row 3
+ 0 | 1 | 3 | 3 // row 4
+ 1 | 1 | 4 | 4 // row 5
+
+``row 1`` and ``row 2`` are in the same partition, ``row 3`` and ``row 4`` are also in the same partition (but a
+different one) and ``row 5`` is in yet another partition.
+
+Note that a table always has a partition key and that if the table has no :ref:`clustering columns
+<clustering-columns>`, then every partition of that table is only comprised of a single row (since the primary key
+uniquely identifies rows and the primary key is equal to the partition key if there are no clustering columns).
+
+The most important property of partition is that all the rows belonging to the same partition are guarantee to be stored
+on the same set of replica nodes. In other words, the partition key of a table defines which of the rows will be
+localized together in the cluster, and it is thus important to choose your partition key wisely so that rows that need
+to be fetched together are in the same partition (so that querying those rows together require contacting a minimum of
+nodes).
+
+However, please note that there is a flip-side to this guarantee: as all rows sharing a partition key are guaranteed to
+be stored on the same set of replica nodes, a partition key that groups too much data can create a hotspot.
+
+Another useful property of a partition is that when writing data, all the updates belonging to a single partition are
+done *atomically* and in *isolation*, which is not the case across partitions.
+
+The proper choice of the partition key and clustering columns for a table is probably one of the most important aspects
+of data modeling in Scylla. It largely impacts which queries can be performed and how efficient they are.
+
+.. note:: An empty string is *not* allowed as a partition key value. In a compound partition key (multiple partition-key columns), any or all of them may be empty strings. Empty string is *not* a Null value.
+
+
+.. _clustering-columns:
+
+The clustering columns
+``````````````````````
+
+The clustering columns of a table define the clustering order for the partition of that table. For a given
+:ref:`partition <partition-key>`, all the rows are physically ordered inside Scylla by that clustering order. For
+instance, given::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ PRIMARY KEY (a, b, c)
+ );
+
+ SELECT * FROM t;
+ a | b | c
+ ---+---+---
+ 0 | 0 | 4 // row 1
+ 0 | 1 | 9 // row 2
+ 0 | 2 | 2 // row 3
+ 0 | 3 | 3 // row 4
+
+then the rows (which all belong to the same partition) are all stored internally in the order of the values of their
+``b`` column (the order they are displayed above). So, where the partition keys of the table let you group rows on the
+same replica set, the clustering columns control how those rows are stored on the replica. That sorting allows the
+retrieval of a range of rows within a partition (for instance, in the example above, ``SELECT * FROM t WHERE a = 0 AND b
+> 1 and b <= 3``) is very efficient.
+
+.. note:: An empty string is allowed as a clustering key value. Empty string is *not* a Null value.
+
+
+.. _create-table-options:
+
+Table options
+~~~~~~~~~~~~~
+
+A CQL table has a number of options that can be set at creation (and, for most of them, :ref:`altered
+<alter-table-statement>` later). These options are specified after the ``WITH`` keyword.
+
+Amongst those options, two important ones cannot be changed after creation and influence which queries can be done
+against the table: the ``COMPACT STORAGE`` option and the ``CLUSTERING ORDER`` option. Those, as well as the other
+options of a table are described in the following sections.
+
+.. _compact-tables:
+
+Compact tables
+``````````````
+
+..
+ .. caution:: Since Apache Cassandra 3.0, compact tables have the exact same layout internally than non compact ones (for the
+ same schema obviously), and declaring a table compact **only** creates artificial limitations on the table definition
+ and usage. It only exists for historical reason and is preserved for backward compatibility And as ``COMPACT
+ STORAGE`` cannot, as of Apache Cassandra |version|, be removed, it is strongly discouraged to create new table with the
+ ``COMPACT STORAGE`` option.
+
+A *compact* table is one defined with the ``COMPACT STORAGE`` option. This option is only maintained for backward
+compatibility for definitions created before CQL version 3 and shouldn't be used for new tables. Declaring a
+table with this option creates limitations for the table, which are largely arbitrary (and exists for historical
+reasons). Amongst these limitations:
+
+- a compact table cannot use collections nor static columns.
+- if a compact table has at least one clustering column, then it must have *exactly* one column outside of the primary
+ key ones. This implies that you cannot add or remove columns in particular after creation.
+- a compact table is limited as to the indexes it can create, and no materialized view can be created on it.
+
+.. _clustering-order:
+
+Reversing the clustering order
+``````````````````````````````
+
+The clustering order of a table is defined by the :ref:`clustering columns <clustering-columns>` of that table. By
+default, that ordering is based on the natural order of the clustering order, but the ``CLUSTERING ORDER`` lets you
+change that clustering order to use the *reverse* natural order for some (potentially all) of the columns.
+
+The ``CLUSTERING ORDER`` option takes the comma-separated list of the clustering column, each with an ``ASC`` (for
+*ascendant*, e.g. the natural order) or ``DESC`` (for *descendant*, e.g. the reverse natural order). Note in particular
+that the default (if the ``CLUSTERING ORDER`` option is not used) is strictly equivalent to using the option with all
+clustering columns using the ``ASC`` modifier.
+
+Note that this option is basically a hint for the storage engine to change the order in which it stores the row, but it
+has three visible consequences:
+
+- it limits which ``ORDER BY`` clause is allowed for :ref:`selects <select-statement>` on that table. You can only
+ order results by the clustering order or the reverse clustering order. Meaning that if a table has two clustering columns
+ ``a`` and ``b``, and you define ``WITH CLUSTERING ORDER (a DESC, b ASC)``, then in queries, you will be allowed to use
+ ``ORDER BY (a DESC, b ASC)`` and (reverse clustering order) ``ORDER BY (a ASC, b DESC)`` but **not** ``ORDER BY (a
+ ASC, b ASC)`` (nor ``ORDER BY (a DESC, b DESC)``).
+- it also changes the default order of results when queried (if no ``ORDER BY`` is provided). Results are always returned
+ in clustering order (within a partition).
+- it has a small performance impact on some queries as queries in reverse clustering order are slower than the one in
+ forward clustering order. In practice, this means that if you plan on querying mostly in the reverse natural order of
+ your columns (which is common with time series, for instance, where you often want data from the newest to the oldest),
+ it is an optimization to declare a descending clustering order.
+
+.. _create-table-general-options:
+
+Other table options
+```````````````````
+
+.. _todo: review (misses cdc if nothing else) and link to proper categories when appropriate (compaction, for instance)
+
+A table supports the following options:
+
+.. list-table::
+ :widths: 20 10 10 60
+ :header-rows: 1
+
+ * - Option
+ - Kind
+ - Default
+ - Description
+ * - ``comment``
+ - simple
+ - none
+ - A free-form, human-readable comment.
+ * - ``read_repair_chance``
+ - simple
+ - 0
+ - The probability that extra nodes are queried (e.g. more nodes than required by the consistency level) for the purpose of read repairs.
+ * - ``dclocal_read_repair_chance``
+ - simple
+ - 0
+ - The probability that extra nodes are queried (e.g. more nodes than required by the consistency level) belonging to the same data center as the read coordinator for the purpose of read repairs.
+ * - ``speculative_retry``
+ - simple
+ - 99PERCENTILE
+ - :ref:`Speculative retry options <speculative-retry-options>`
+ * - ``gc_grace_seconds``
+ - simple
+ - 864000
+ - Time to wait before garbage collecting tombstones (deletion markers). See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+ * - ``tombstone_gc``
+ - mode
+ - see below
+ - The mode of garbage collecting tombstones. See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+ * - ``bloom_filter_fp_chance``
+ - simple
+ - 0.01
+ - The target probability of false-positive of the sstable bloom filters. Sstable bloom filters will be sized to provide the provided probability (thus lowering this value impact the size of bloom filters in-memory and on-disk).
+ * - ``default_time_to_live``
+ - simple
+ - 0
+ - The default expiration time (“TTL”) in seconds for a table.
+ * - ``compaction``
+ - map
+ - see below
+ - :ref:`Compaction options <cql-compaction-options>`
+ * - ``compaction``
+ - map
+ - see below
+ - :ref:`Compression options <cql-compression-options>`
+ * - ``caching``
+ - map
+ - see below
+ - :ref:`Caching Options <cql-caching-options>`
+ * - ``cdc``
+ - map
+ - see below
+ - :ref:`CDC Options <cdc-options>`
+
+
+.. _speculative-retry-options:
+
+Speculative retry options
+#########################
+
+By default, Scylla read coordinators only query as many replicas as necessary to satisfy
+consistency levels: one for consistency level ``ONE``, a quorum for ``QUORUM``, and so on.
+``speculative_retry`` determines when coordinators may query additional replicas, which is useful
+when replicas are slow or unresponsive. The following are legal values (case-insensitive):
+
+========================= ================ =============================================================================
+ Format Example Description
+========================= ================ =============================================================================
+ ``XPERCENTILE`` 90.5PERCENTILE Coordinators record average per-table response times for all replicas.
+ If a replica takes longer than ``X`` percent of this table's average
+ response time, the coordinator queries an additional replica.
+ ``X`` must be between 0 and 100.
+ ``XP`` 90.5P Synonym for ``XPERCENTILE``
+ ``Yms`` 25ms If a replica takes more than ``Y`` milliseconds to respond,
+ the coordinator queries an additional replica.
+ ``ALWAYS`` Coordinators always query all replicas.
+ ``NONE`` Coordinators never query additional replicas.
+========================= ================ =============================================================================
+
+This setting does not affect reads with consistency level ``ALL`` because they already query all replicas.
+
+Note that frequently reading from additional replicas can hurt cluster performance.
+When in doubt, keep the default ``99PERCENTILE``.
+
+
+.. _cql-compaction-options:
+
+Compaction options
+##################
+
+The ``compaction`` options must at least define the ``'class'`` sub-option, which defines the compaction strategy class
+to use. The default supported class are ``'SizeTieredCompactionStrategy'``,
+``'LeveledCompactionStrategy'``, ``'IncrementalCompactionStrategy'``, and ``'DateTieredCompactionStrategy'``
+Custom strategy can be provided by specifying the full class name as a :ref:`string constant
+<constants>`.
+
+All default strategies support a number of common options, as well as options specific to
+the strategy chosen (see the section corresponding to your strategy for details: :ref:`STCS <stcs-options>`, :ref:`LCS <lcs-options>`, :ref:`ICS <ics-options>`, and :ref:`TWCS <twcs-options>`). DTCS is not recommended, and TWCS should be used instead.
+
+
+.. ``'Date Tiered Compaction Strategy is not recommended and has been replaced by Time Window Compaction Stragegy.'`` (:ref:`TWCS <TWCS>`) (the
+.. is also supported but is deprecated and ``'TimeWindowCompactionStrategy'`` should be
+.. preferred instead).
+
+
+
+.. _cql-compression-options:
+
+Compression options
+###################
+
+The ``compression`` options define if and how the sstables of the table are compressed. The following sub-options are
+available:
+
+========================= =============== =============================================================================
+ Option Default Description
+========================= =============== =============================================================================
+ ``sstable_compression`` LZ4Compressor The compression algorithm to use. Default compressors are
+ LZ4Compressor, SnappyCompressor, and DeflateCompressor.
+ A custom compressor can be provided by specifying the full class
+ name as a “string constant”:#constants.
+ ``chunk_length_in_kb`` 4KB On disk SSTables are compressed by block (to allow random reads). This
+ defines the size (in KB) of the block. Bigger values may improve the
+ compression rate, but increases the minimum size of data to be read from disk
+ for a read.
+========================= =============== =============================================================================
+
+.. ``crc_check_chance`` 1.0 When compression is enabled, each compressed block includes a checksum of
+.. that block for the purpose of detecting disk bitrot and avoiding the
+.. propagation of corruption to other replicas. This option defines the
+.. probability with which those checksums are checked during read. By default
+.. they are always checked. Set to 0 to disable checksum checking and to 0.5 for
+.. instance to check them every other read |
+
+For example, to enable compression:
+
+.. code-block:: console
+
+
+ CREATE TABLE id (id int PRIMARY KEY) WITH compression = {'sstable_compression': 'LZ4Compressor'};
+
+
+For example, to disable compression:
+
+.. code-block:: console
+
+ CREATE TABLE id (id int PRIMARY KEY) WITH compression = {};
+
+
+.. _cdc-options:
+
+CDC options
+###########
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The following options are to be used with Change Data Capture. Available as an experimental feature from Scylla Open Source 3.2.
+To use this feature, you must enable the :ref:`experimental tag <yaml_enabling_experimental_features>` in the scylla.yaml.
+
+
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| option | default | description |
++===========================+=================+========================================================================================================================+
+| ``enabled`` | ``false`` | When set to ``true``, another table --- the CDC log table --- is created and associated with the table you are |
+| | | creating/altering (for example, customer_data). All writes made to this table (customer_data) are reflected in |
+| | | the corresponding CDC log table. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| ``preimage`` | ``false`` | When set to ``true``, it saves the result of what a client performing a write would display if it has queried this |
+| | | table before making the write into the corresponding CDC log table. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| ``ttl`` | 86400 seconds | Time after which data stored in CDC will be removed and won’t be accessible to the client anymore. |
+| | 24 hours | |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+
+For example:
+
+.. code-block:: cql
+
+ CREATE TABLE customer_data (
+ cust_id uuid,
+ cust_first-name text,
+ cust_last-name text,
+ cust_phone text,
+ cust_get-sms text,
+ PRIMARY KEY (customer_id)
+ ) WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };
+
+.. _cql-caching-options:
+
+Caching options
+###############
+
+Caching optimizes cache memory usage of a table. The cached data is weighed by size and access frequency.
+
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+| option | default | description |
++===========================+=================+========================================================================================================================+
+| ``enabled`` | ``TRUE`` | When set to TRUE enables caching on the specified table. Valid options are TRUE and FALSE. |
++---------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------+
+
+
+For example,
+
+.. code-block:: cql
+
+ CREATE TABLE caching (
+ k int PRIMARY KEY,
+ v1 int,
+ v2 int,
+ ) WITH caching = {'enabled': 'true'};
+
+Encryption options
+###################
+
+Encryption options are used when enabling or disabling encryption at rest, available in Scylla Enterprise from version 2019.1.1.
+
+.. note:: When the ``key_provider`` is ``LocalFileSystemKeyProviderFactory``, you must indicate where the key resides using the ``secret_key_file: <path>`` parameter. Refer to :doc:`Encryption at Rest </operating-scylla/security/encryption-at-rest>` for details.
+
+.. _ddl-tombstones-gc:
+.. _gc_grace_seconds:
+
+Tombstones GC options
+#######################
+
+ScyllaDB inherited the ``gc_grace_seconds`` option from Apache Cassandra. The option allows you to specify the wait time
+(in seconds) before data marked with a deletion :term:`tombstone` is removed via compaction.
+This option assumes that you run :term:`repair` during the specified time. Failing to run repair during the wait
+time may result in the resurrection of deleted data.
+
+The ``tombstone_gc`` option allows you to prevent data resurrection. With the ``repair`` mode configured, :term:`tombstone`
+are only removed after :term:`repair` is performed. Unlike ``gc_grace_seconds``, ``tombstone_gc`` has no time constraints - when
+the ``repair`` mode is on, tombstones garbage collection will wait until repair is run.
+
+The ``tombstone_gc`` option can be enabled using ``ALTER TABLE`` and ``CREATE TABLE``. For example:
+
+.. code-block:: cql
+
+ CREATE TABLE ks.cf (key blob PRIMARY KEY, val blob) WITH tombstone_gc = {'mode':'repair'};
+
+.. code-block:: cql
+
+ ALTER TABLE ks.cf WITH tombstone_gc = {'mode':'repair'} ;
+
+.. note::
+ The ``tombstone_gc`` option was added in ScyllaDB 5.0 as an experimental feature, and it is disabled by default.
+ You need to explicitly specify the ``repair`` mode table property to enable the feature.
+
+The following modes are available:
+
+.. list-table::
+ :widths: 20 80
+ :header-rows: 1
+
+ * - Mode
+ - Description
+ * - ``timeout``
+ - Tombstone GC is performed after the wait time specified with ``gc_grace_seconds``. Default in ScyllaDB 5.0.
+ * - ``repair``
+ - Tombstone GC is performed after repair is run.
+ * - ``disabled``
+ - Tombstone GC is never performed. This mode may be useful when loading data to the database, to avoid tombstone GC when part of the data is not yet available.
+ * - ``immediate``
+ - Tombstone GC is immediately performed. There is no wait time or repair requirement. This mode is useful for a table that uses the TWCS compaction strategy with no user deletes. After data is expired after TTL, ScyllaDB can perform compaction to drop the expired data immediately.
+
+Other considerations:
+#####################
+
+- Adding new columns (see ``ALTER TABLE`` below) is a constant time operation. There is thus no need to try to
+ anticipate future usage when creating a table.
+
+.. _alter-table-statement:
+
+ALTER TABLE
+^^^^^^^^^^^
+
+Altering an existing table uses the ``ALTER TABLE`` statement:
+
+.. code-block:: cql
+
+ alter_table_statement: ALTER TABLE `table_name` `alter_table_instruction`
+ alter_table_instruction: ADD `column_name` `cql_type` ( ',' `column_name` `cql_type` )*
+ : | DROP `column_name`
+ : | DROP '(' `column_name` ( ',' `column_name` )* ')'
+ : | ALTER `column_name` TYPE `cql_type`
+ : | WITH `options`
+ : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'
+
+For instance:
+
+.. code-block:: cql
+
+ ALTER TABLE addamsFamily ADD gravesite varchar;
+
+ ALTER TABLE addamsFamily
+ WITH comment = 'A most excellent and useful table'
+ AND read_repair_chance = 0.2;
+
+
+ ALTER TABLE data_atrest (
+ pk text PRIMARY KEY,
+ c0 int
+ ) WITH scylla_encryption_options = {
+ 'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
+ 'secret_key_strength' : 128,
+ 'key_provider': 'LocalFileSystemKeyProviderFactory',
+ 'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};
+
+ ALTER TABLE customer_data
+ WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };
+
+The ``ALTER TABLE`` statement can:
+
+- Add new column(s) to the table (through the ``ADD`` instruction). Note that the primary key of a table cannot be
+ changed, and thus newly added column will, by extension, never be part of the primary key. Also, note that :ref:`compact
+ tables <compact-tables>` have restrictions regarding column addition. Note that this is constant (in the amount of
+ data the cluster contains) time operation.
+- Remove column(s) from the table. This drops both the column and all its content, but note that while the column
+ becomes immediately unavailable, its content is only removed lazily during compaction. Please also note the warnings
+ below. Due to lazy removal, the altering itself is a constant (in the amount of data removed or contained in the
+ cluster) time operation.
+- Change data type of the column to a compatible type.
+- Change some of the table options (through the ``WITH`` instruction). The :ref:`supported options
+ <create-table-options>` are the same that when creating a table (outside of ``COMPACT STORAGE`` and ``CLUSTERING
+ ORDER`` that cannot be changed after creation). Note that setting any ``compaction`` sub-options has the effect of
+ erasing all previous ``compaction`` options, so you need to re-specify all the sub-options if you want to keep them.
+ The same note applies to the set of ``compression`` sub-options.
+- Change or add any of the ``Encryption options`` above.
+- Change or add any of the :ref:`CDC options <cdc-options>` above.
+
+.. warning:: Dropping a column assumes that the timestamps used for the value of this column are "real" timestamp in
+ microseconds. Using "real" timestamps in microseconds is the default is and is **strongly** recommended, but as
+ Scylla allows the client to provide any timestamp on any table, it is theoretically possible to use another
+ convention. Please be aware that if you do so, dropping a column will not work correctly.
+
+.. warning:: Once a column is dropped, it is allowed to re-add a column with the same name as the dropped one
+ **unless** the type of the dropped column was a (non-frozen) column (due to an internal technical limitation).
+
+
+.. _drop-table-statement:
+
+DROP TABLE
+^^^^^^^^^^
+
+Dropping a table uses the ``DROP TABLE`` statement:
+
+.. code-block::
+
+ drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name`
+
+Dropping a table results in the immediate removal of the table, including all data it contains.
+
+.. include:: /getting-started/_common/note-reclaim-space.rst
+
+If the table does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case the
+operation is a no-op.
+
+.. _truncate-statement:
+
+TRUNCATE
+^^^^^^^^
+
+A table can be truncated using the ``TRUNCATE`` statement:
+
+.. code-block::
+
+ truncate_statement: TRUNCATE [ TABLE ] `table_name`
+
+Note that ``TRUNCATE TABLE foo`` is allowed for consistency with other DDL statements, but tables are the only object
+that can be truncated currently and so the ``TABLE`` keyword can be omitted.
+
+Truncating a table permanently removes all existing data from the table, but without removing the table itself.
+
+.. caution:: Do not run any operation on a table that is being truncated. Truncate operation is an administrative operation, and running any other operation on the same table in parallel may cause the truncating table's data to end up in an undefined state.
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
\ No newline at end of file
diff --git a/docs/getting-started/definitions.rst b/docs/getting-started/definitions.rst
--- a/docs/getting-started/definitions.rst
+++ b/docs/getting-started/definitions.rst
@@ -0,0 +1,226 @@
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+.. highlight:: cql
+
+Definitions
+-----------
+
+.. include:: /rst_include/cql-version-index.rst
+
+.. _conventions:
+
+Conventions
+^^^^^^^^^^^
+
+To aid in specifying the CQL syntax, we will use the following conventions in this document:
+
+- Language rules will be given in an informal `BNF variant
+ <http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form#Variants>`_ notation. In particular, we'll use square brackets
+ (``[ item ]``) for optional items, ``*`` and ``+`` for repeated items (where ``+`` imply at least one).
+- The grammar will also use the following convention for convenience: non-terminal term will be lowercase (and link to
+ their definition) while terminal keywords will be provided "all caps". Note, however, that keywords are
+ :ref:`identifiers` and are thus case insensitive in practice. We will also define some early construction using
+ regexp, which we'll indicate with ``re(<some regular expression>)``.
+- The grammar is provided for documentation purposes and leaves some minor details out. For instance, the comma on the
+ last column definition in a ``CREATE TABLE`` statement is optional but supported if present even though the grammar in
+ this document suggests otherwise. Also, not everything accepted by the grammar is necessarily valid CQL.
+- References to keywords or pieces of CQL code in running text will be shown in a ``fixed-width font``.
+
+
+.. _identifiers:
+
+Identifiers and keywords
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The CQL language uses *identifiers* (or *names*) to identify tables, columns, and other objects. An identifier is a token
+matching the regular expression ``[a-zA-Z][a-zA-Z0-9_]*``.
+
+A number of such identifiers, like ``SELECT`` or ``WITH``, are *keywords*. They have a fixed meaning for the language,
+and most are reserved. The list of those keywords can be found in :ref:`appendix-A`.
+
+Identifiers and (unquoted) keywords are case insensitive. Thus ``SELECT`` is the same as ``select`` or ``sElEcT``, and
+``myId`` is the same than ``myid`` or ``MYID``. A convention often used (in particular by the samples of this
+documentation) is to use upper case for keywords and lower case for other identifiers.
+
+There is a second kind of identifier called *quoted identifiers*, defined by enclosing an arbitrary sequence of
+characters (non-empty) in double-quotes(``"``). Quoted identifiers are never keywords. Thus ``"select"`` is not a
+reserved keyword and can be used to refer to a column (note that using this is particularly advised), while ``select``
+would raise a parsing error. Also, contrary to unquoted identifiers and keywords, quoted identifiers are case
+sensitive (``"My Quoted Id"`` is *different* from ``"my quoted id"``). A fully lowercase quoted identifier that matches
+``[a-zA-Z][a-zA-Z0-9_]*`` is, however, *equivalent* to the unquoted identifier obtained by removing the double-quote (so
+``"myid"`` is equivalent to ``myid`` and to ``myId`` but different from ``"myId"``). Inside a quoted identifier, the
+double-quote character can be repeated to escape it, so ``"foo "" bar"`` is a valid identifier.
+
+.. note:: *quoted identifiers* allow to declare columns with arbitrary names, and those can sometimes clash with
+ specific names used by the server. For instance, when using a conditional update, the server will respond with a
+ result-set containing a special result named ``"[applied]"``. If you’ve declared a column with such a name, this
+ could potentially confuse some tools and should be avoided. In general, unquoted identifiers should be preferred, but
+ if you use quoted identifiers, it is strongly advised to avoid any name enclosed by squared brackets (like
+ ``"[applied]"``) and any name that looks like a function call (like ``"f(x)"``).
+
+More formally, we have:
+
+.. code-block::
+
+ identifier: `unquoted_identifier` | `quoted_identifier`
+ unquoted_identifier: re('[a-zA-Z][a-zA-Z0-9_]*')
+ quoted_identifier: '"' (any character where " can appear if doubled)+ '"'
+
+.. _constants:
+
+Constants
+^^^^^^^^^
+
+CQL defines the following kind of *constants*:
+
+.. code-block:: none
+
+ constant: `string` | `integer` | `float` | `boolean` | `uuid` | `blob` | NULL
+
+ string: '\'' (any character where ' can appear if doubled)+ '\''
+ : '$$' (any character other than '$$') '$$'
+
+ integer: re('-?[0-9]+')
+
+ float: re('-?[0-9]+(\.[0-9]*)?([eE][+-]?[0-9+])?') | NAN | INFINITY
+
+ boolean: TRUE | FALSE
+
+ uuid: `hex`{8}-`hex`{4}-`hex`{4}-`hex`{4}-`hex`{12}
+
+ hex: re("[0-9a-fA-F]")
+
+ blob: '0' ('x' | 'X') `hex`+
+
+In other words:
+
+- A string constant is an arbitrary sequence of characters enclosed by single-quote(``'``). A single-quote
+ can be included by repeating it, e.g. ``'It''s raining today'``. Those are not to be confused with quoted
+ :ref:`identifiers` that use double-quotes. Alternatively, a string can be defined by enclosing the arbitrary sequence
+ of characters by two dollar characters, in which case single-quote can be used without escaping (``$$It's raining
+ today$$``). That latter form is often used when defining user-defined functions to avoid having to
+ escape single-quote characters in function body (as they are more likely to occur than ``$$``).
+- Integer, float, and boolean constant are defined as expected. Note, however, than float allows the special ``NaN`` and
+ ``Infinity`` constants.
+- CQL supports UUID_ constants.
+- Blob content types are provided in hexadecimal and prefixed by ``0x``.
+- The special ``NULL`` constant denotes the absence of value.
+
+For how these constants are typed, see the :doc:`data-types <types>` document.
+
+Terms
+^^^^^
+
+CQL has the notion of a *term*, which denotes the kind of values that CQL support. Terms are defined by:
+
+.. code-block:: cql
+
+ term: `constant` | `literal` | `function_call` | `arithmetic_operation` | `type_hint` | `bind_marker`
+
+ literal: `collection_literal` | `udt_literal` | `tuple_literal`
+
+ function_call: `identifier` '(' [ `term` (',' `term`)* ] ')'
+
+ arithmetic_operation: '-' `term` | `term` ('+' | '-' | '*' | '/' | '%') `term`
+
+ type_hint: '(' `cql_type` `)` term
+
+ bind_marker: '?' | ':' `identifier`
+
+A term is thus one of:
+
+- A :ref:`constant <constants>`.
+- A literal for either :ref:`a collection <collections>`, a user-defined type or a tuple
+ (see the linked sections for details).
+- An arithmetic operation between terms.
+- A *type hint*
+- A bind marker, which denotes a variable to be bound at execution time. See the section on :ref:`prepared-statements`
+ for details. A bind marker can be either anonymous (``?``) or named (``:some_name``). The latter form provides a more
+ convenient way to refer to the variable for binding it and should generally be preferred.
+
+
+Comments
+^^^^^^^^
+
+A comment in CQL is a line beginning by either double dashes (``--``) or double slash (``//``).
+
+Multi-line comments are also supported through enclosure within ``/*`` and ``*/`` (but nesting is not supported).
+
+::
+
+ -- This is a comment
+ // This is a comment too
+ /* This is
+ a multi-line comment */
+
+Statements
+^^^^^^^^^^
+
+CQL consists of statements that can be divided into the following categories:
+
+- :doc:`Data Definition </getting-started/ddl/>` statements - to define and change how the data is stored (keyspaces and tables).
+- :doc:`Data Manipulation </getting-started/dml/>` statements - for selecting, inserting and deleting data.
+- :ref:`cql-permissions` statements.
+- cql-triggers statements.
+
+All the statements are listed below and are described in the rest of this documentation (see links above):
+
+.. code-block:: cql
+
+ cql_statement: `statement` [ ';' ]
+ statement: `ddl_statement`
+ : | `dml_statement`
+ : | `secondary_index_statement`
+ : | `materialized_view_statement`
+ : | `role_or_permission_statement`
+ : | `udf_statement`
+ : | `udt_statement`
+ : | `trigger_statement`
+ ddl_statement: `use_statement`
+ : | `create_keyspace_statement`
+ : | `alter_keyspace_statement`
+ : | `drop_keyspace_statement`
+ : | `create_table_statement`
+ : | `alter_table_statement`
+ : | `drop_table_statement`
+ : | `truncate_statement`
+ dml_statement: `select_statement`
+ : | `insert_statement`
+ : | `update_statement`
+ : | `delete_statement`
+ : | `batch_statement`
+ trigger_statement: `create_trigger_statement`
+ : | `drop_trigger_statement`
+
+.. _prepared-statements:
+
+Prepared Statements
+^^^^^^^^^^^^^^^^^^^
+
+CQL supports *prepared statements*. Prepared statements are an optimization that allows parsing a query only once but
+executes it multiple times with different concrete values.
+
+Any statement that uses at least one bind marker (see :token:`bind_marker`) will need to be *prepared*. After which, the statement
+can be *executed* by provided concrete values for each of its markers. The exact details of how a statement is prepared
+and then executed depends on the CQL driver used, and you should refer to your driver documentation.
+
+
+.. include:: /rst_include/apache-copyrights-index.rst
+.. include:: /rst_include/apache-cql-return-index.rst
diff --git a/docs/getting-started/dml.rst b/docs/getting-started/dml.rst
--- a/docs/getting-started/dml.rst
+++ b/docs/getting-started/dml.rst
@@ -0,0 +1,974 @@
+.. highlight:: cql
+
+Data Manipulation
+-----------------
+
+.. include:: /rst_include/cql-version-index.rst
+
+This section describes the statements supported by CQL to insert, update, delete, and query data.
+
+:ref:`SELECT <select-statement>`
+
+.. _select:
+
+:ref:`INSERT <insert-statement>`
+
+.. _insert:
+
+:ref:`UPDATE <update-statement>`
+
+.. _update:
+
+:ref:`DELETE <delete_statement>`
+
+.. _delete:
+
+:ref:`BATCH <batch_statement>`
+
+.. _batch:
+
+
+.. _select-statement:
+
+SELECT
+^^^^^^
+
+Querying data from data is done using a ``SELECT`` statement:
+
+.. code-block::
+
+ select_statement: SELECT [ DISTINCT ] ( `select_clause` | '*' )
+ : FROM `table_name`
+ : [ WHERE `where_clause` ]
+ : [ GROUP BY `group_by_clause` ]
+ : [ ORDER BY `ordering_clause` ]
+ : [ PER PARTITION LIMIT (`integer` | `bind_marker`) ]
+ : [ LIMIT (`integer` | `bind_marker`) ]
+ : [ ALLOW FILTERING ]
+ : [ BYPASS CACHE ]
+ : [ USING TIMEOUT `timeout` ]
+ select_clause: `selector` [ AS `identifier` ] ( ',' `selector` [ AS `identifier` ] )*
+ selector: `column_name`
+ : | CAST '(' `selector` AS `cql_type` ')'
+ : | `function_name` '(' [ `selector` ( ',' `selector` )* ] ')'
+ : | COUNT '(' '*' ')'
+ where_clause: `relation` ( AND `relation` )*
+ relation: `column_name` `operator` `term`
+ : '(' `column_name` ( ',' `column_name` )* ')' `operator` `tuple_literal`
+ : TOKEN '(' `column_name` ( ',' `column_name` )* ')' `operator` `term`
+ operator: '=' | '<' | '>' | '<=' | '>=' | IN | CONTAINS | CONTAINS KEY
+ ordering_clause: `column_name` [ ASC | DESC ] ( ',' `column_name` [ ASC | DESC ] )*
+ timeout: `duration`
+
+For instance::
+
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207);
+ SELECT name AS user_name, occupation AS user_occupation FROM users;
+
+ SELECT time, value
+ FROM events
+ WHERE event_type = 'myEvent'
+ AND time > '2011-02-03'
+ AND time <= '2012-01-01'
+
+ SELECT COUNT (*) AS user_count FROM users;
+
+ SELECT * FROM users WHERE event_type = 'myEvent' USING TIMEOUT 50ms;
+
+The ``SELECT`` statement reads one or more columns for one or more rows in a table. It returns a result-set of the rows
+matching the request, where each row contains the values for the selection corresponding to the query. Additionally,
+functions, including aggregation ones, can be applied to the result.
+
+A ``SELECT`` statement contains at least a :ref:`selection clause <selection-clause>` and the name of the table on which
+the selection is on (note that CQL does **not** support joins or sub-queries, and thus a select statement only applies to a single
+table). In most cases, a select will also have a :ref:`where clause <where-clause>` and it can optionally have additional
+clauses to :ref:`order <ordering-clause>` or :ref:`limit <limit-clause>` the results. Lastly, :ref:`queries that require
+filtering <allow-filtering>` can be allowed if the ``ALLOW FILTERING`` flag is provided.
+
+If your ``SELECT`` query results in what appears to be missing data, see this :doc:`KB Article </kb/cqlsh-results>` for information.
+
+.. _selection-clause:
+
+Selection clause
+~~~~~~~~~~~~~~~~
+
+The :token:`select_clause` determines which columns need to be queried and returned in the result-set, as well as any
+transformation to apply to this result before returning. It consists of a comma-separated list of *selectors* or,
+alternatively, of the wildcard character (``*``) to select all the columns defined in the table.
+
+Selectors
+`````````
+
+A :token:`selector` can be one of:
+
+- A column name of the table selected to retrieve the values for that column.
+- A casting, which allows you to convert a nested selector to a (compatible) type.
+- A function call, where the arguments are selector themselves.
+
+Aliases
+```````
+
+Every *top-level* selector can also be aliased (using `AS`). If so, the name of the corresponding column in the result
+set will be that of the alias. For instance::
+
+ // Without alias
+ SELECT intAsBlob(4) FROM t;
+
+ // intAsBlob(4)
+ // --------------
+ // 0x00000004
+
+ // With alias
+ SELECT intAsBlob(4) AS four FROM t;
+
+ // four
+ // ------------
+ // 0x00000004
+
+.. note:: Currently, aliases aren't recognized anywhere else in the statement where they are used (not in the ``WHERE``
+ clause, not in the ``ORDER BY`` clause, ...). You must use the original column name instead.
+
+
+``WRITETIME`` and ``TTL`` function
+```````````````````````````````````
+
+Selection supports two special functions (which aren't allowed anywhere else): ``WRITETIME`` and ``TTL``. Both functions
+take only one argument, and that argument *must* be a column name (so, for instance, ``TTL(3)`` is invalid).
+
+Those functions let you retrieve meta-information that is stored internally for each column, namely:
+
+- ``WRITETIME`` retrieves the timestamp used when writing the column. The timestamp is typically the number of *microseconds* since the `Unix epoch <https://en.wikipedia.org/wiki/Unix_time>`_ (January 1st 1970 at 00:00:00 UTC).
+
+You can read more about the ``TIMESTAMP`` retrieved by ``WRITETIME`` in the :ref:`UPDATE <update-parameters>` section.
+
+- ``TTL`` retrieves the remaining time to live (in *seconds*) for the value of the column, if it set to expire, or ``null`` otherwise.
+
+You can read more about TTL in the :doc:`documentation </getting-started/time-to-live>` and also in `this Scylla University lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`.
+
+.. _where-clause:
+
+The ``WHERE`` clause
+~~~~~~~~~~~~~~~~~~~~
+
+The ``WHERE`` clause specifies which rows must be queried. It is composed of relations on the columns that are part of
+the ``PRIMARY KEY``.
+
+Not all relations are allowed in a query. For instance, non-equal relations (where ``IN`` is considered as an equal
+relation) on a partition key are not supported (see the use of the ``TOKEN`` method below to do non-equal queries on
+the partition key). Moreover, for a given partition key, the clustering columns induce an ordering of rows and relations
+on them restricted to the relations that let you select a **contiguous** (for the ordering) set of rows. For
+instance, given::
+
+ CREATE TABLE posts (
+ userid text,
+ blog_title text,
+ posted_at timestamp,
+ entry_title text,
+ content text,
+ category int,
+ PRIMARY KEY (userid, blog_title, posted_at)
+ )
+
+The following query is allowed::
+
+ SELECT entry_title, content FROM posts
+ WHERE userid = 'john doe'
+ AND blog_title='John''s Blog'
+ AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31'
+
+But the following query is not, as it does not select a contiguous set of rows (and we suppose no secondary indexes are
+set)::
+
+ // Needs a blog_title to be set to select ranges of posted_at
+ SELECT entry_title, content FROM posts
+ WHERE userid = 'john doe'
+ AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31'
+
+When specifying relations, the ``TOKEN`` function can be used on the ``PARTITION KEY`` column to query. In that case,
+rows will be selected based on the token of their ``PARTITION_KEY`` rather than on the value. Note that the token of a
+key depends on the partitioner in use and that, in particular, the RandomPartitioner won't yield a meaningful order. Also
+note that ordering partitioners always order token values by bytes (so even if the partition key is of type int,
+``token(-1) > token(0)`` in particular). For example::
+
+ SELECT * FROM posts
+ WHERE token(userid) > token('tom') AND token(userid) < token('bob')
+
+Moreover, the ``IN`` relation is only allowed on the last column of the partition key and on the last column of the full
+primary key.
+
+It is also possible to “group” ``CLUSTERING COLUMNS`` together in a relation using the tuple notation. For instance::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND (blog_title, posted_at) > ('John''s Blog', '2012-01-01')
+
+will request all rows that sort after the one having “John's Blog” as ``blog_title`` and '2012-01-01' for ``posted_at``
+in the clustering order. In particular, rows having a ``post_at <= '2012-01-01'`` will be returned as long as their
+``blog_title > 'John''s Blog'``, which would not be the case for::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND blog_title > 'John''s Blog'
+ AND posted_at > '2012-01-01'
+
+The tuple notation may also be used for ``IN`` clauses on clustering columns::
+
+ SELECT * FROM posts
+ WHERE userid = 'john doe'
+ AND (blog_title, posted_at) IN (('John''s Blog', '2012-01-01'), ('Extreme Chess', '2014-06-01'))
+
+The ``CONTAINS`` operator may only be used on collection columns (lists, sets, and maps). In the case of maps,
+``CONTAINS`` applies to the map values. The ``CONTAINS KEY`` operator may only be used on map columns and applies to the
+map keys.
+
+.. _group-by-clause:
+
+Grouping results
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The ``GROUP BY`` option lets you condense into a single row all selected rows that share the same values for a set of columns.
+Using the ``GROUP BY`` option, it is only possible to group rows at the partition key level or at a clustering column level.
+The ``GROUP BY`` arguments must form a prefix of the primary key.
+
+For example, if the primary key is ``(p1, p2, c1, c2)``, then the following queries are valid::
+
+ GROUP BY p1
+ GROUP BY p1, p2
+ GROUP BY p1, p2, c1
+ GROUP BY p1, p2, c1, c2
+
+The following should be considered when using the ``GROUP BY`` option:
+
+* If a primary key column is restricted by an equality restriction, it is not required to be present in the ``GROUP BY`` clause.
+
+* Aggregate functions will produce a separate value for each group.
+
+* If no ``GROUP BY`` clause is specified, aggregate functions will produce a single value for all the rows.
+
+* If a column is selected without an aggregate function, in a statement with a ``GROUP BY``, the first value encounter in each group will be returned.
+
+
+.. _ordering-clause:
+
+Ordering results
+~~~~~~~~~~~~~~~~
+
+The ``ORDER BY`` clause lets you select the order of the returned results. It takes as argument a list of column names
+along with the order for the column (``ASC`` for ascendant and ``DESC`` for descendant, omitting the order being
+equivalent to ``ASC``). Currently, the possible orderings are limited by the :ref:`clustering order <clustering-order>`
+defined on the table:
+
+- If the table has been defined without any specific ``CLUSTERING ORDER``, then allowed orderings are the order
+ induced by the clustering columns and the reverse of that one.
+- Otherwise, the orderings allowed are the order of the ``CLUSTERING ORDER`` option and the reversed one.
+
+.. _limit-clause:
+
+Limiting results
+~~~~~~~~~~~~~~~~
+
+.. versionchanged:: 3.1 Scylla Open Source
+
+The ``LIMIT`` option to a ``SELECT`` statement limits the number of rows returned by a query, while the ``PER PARTITION
+LIMIT`` option (introduced in Scylla 3.1) limits the number of rows returned for a given **partition** by the query. Note that both types of limit can be
+used in the same statement.
+
+Examples:
+
+The Partition Key in the following table is ``client_id``, and the clustering key is ``when``.
+The table has seven rows, split between four clients (partition keys)
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM test;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 2 | 2020-02-11 22:00:00.000000+0000
+ 2 | 2020-02-12 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (7 rows)
+
+
+You can ask the query to limit the number of rows returned from **all partition** with LIMIT, for example:
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test LIMIT 3;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+
+ (3 rows)
+
+You can ask the query to limit the number of rows returned for **each** ``client_id``. For example, with limit of *1* :
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 1;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (4 rows)
+
+Increasing limit to *2*, would yield:
+
+.. code-block:: cql
+
+ cqlsh:ks1> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 2;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 1 | 2020-01-01 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 2 | 2020-02-11 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+ 3 | 2020-02-10 22:00:00.000000+0000
+
+ (6 rows)
+
+You can also mix the two limits types:
+
+.. code-block:: cql
+
+ cqlsh> SELECT client_id, when FROM ks1.test PER PARTITION LIMIT 1 LIMIT 3;
+
+ client_id | when
+ -----------+---------------------------------
+ 1 | 2019-12-31 22:00:00.000000+0000
+ 2 | 2020-02-10 22:00:00.000000+0000
+ 4 | 2020-02-10 22:00:00.000000+0000
+
+ (3 rows)
+
+
+.. _allow-filtering:
+
+Allowing filtering
+~~~~~~~~~~~~~~~~~~
+
+By default, CQL only allows select queries that don't involve “filtering” server-side, i.e. queries where we know that
+all (live) record read will be returned (maybe partly) in the result set. The reasoning is that those “non filtering”
+queries have predictable performance in the sense that they will execute in a time that is proportional to the amount of
+data **returned** by the query (which can be controlled through ``LIMIT``).
+
+The ``ALLOW FILTERING`` option lets you explicitly allow (some) queries that require filtering. Please note that a
+query using ``ALLOW FILTERING`` may thus have unpredictable performance (for the definition above), i.e. even a query
+that selects a handful of records **may** exhibit performance that depends on the total amount of data stored in the
+cluster.
+
+For instance, consider the following table holding user profiles with their year of birth (with a secondary index on
+it) and country of residence::
+
+ CREATE TABLE users (
+ username text PRIMARY KEY,
+ firstname text,
+ lastname text,
+ birth_year int,
+ country text
+ )
+
+ CREATE INDEX ON users(birth_year);
+
+Then the following queries are valid::
+
+ SELECT * FROM users;
+ SELECT * FROM users WHERE birth_year = 1981;
+
+because in both cases, Scylla guarantees that these queries' performance will be proportional to the amount of data
+returned. In particular, if no users were born in 1981, then the second query performance will not depend on the number
+of user profiles stored in the database (not directly at least: due to secondary index implementation consideration, this
+query may still depend on the number of nodes in the cluster, which indirectly depends on the amount of data stored.
+Nevertheless, the number of nodes will always be multiple orders of magnitude lower than the number of user profiles
+stored). Of course, both queries may return very large result sets in practice, but the amount of data returned can always
+be controlled by adding a ``LIMIT``.
+
+However, the following query will be rejected::
+
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR';
+
+because Scylla cannot guarantee that it won't have to scan a large amount of data even if the result of those queries is
+small. Typically, it will scan all the index entries for users born in 1981 even if only a handful are actually from
+France. However, if you “know what you are doing”, you can force the execution of this query by using ``ALLOW
+FILTERING`` and so the following query is valid::
+
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING;
+
+.. _bypass-cache:
+
+Bypass Cache
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: Scylla Enterprise 2019.1.1
+.. versionadded:: Scylla 3.1
+
+
+The ``BYPASS CACHE`` clause on SELECT statements informs the database that the data being read is unlikely to be read again in the near future, and also was unlikely to have been read in the near past; therefore, no attempt should be made to read it from the cache or to populate the cache with the data. This is mostly useful for range scans; these typically process large amounts of data with no temporal locality and do not benefit from the cache.
+The clause is placed immediately after the optional ALLOW FILTERING clause.
+
+``BYPASS CACHE`` is a Scylla CQL extension and not part of Apache Cassandra CQL.
+
+For example::
+
+ SELECT * FROM users BYPASS CACHE;
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207) BYPASS CACHE;
+ SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING BYPASS CACHE;
+
+.. _using-timeout:
+
+Using Timeout
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: Scylla 4.4
+
+The ``USING TIMEOUT`` clause allows specifying a timeout for a specific request.
+
+For example::
+
+ SELECT * FROM users USING TIMEOUT 5s;
+ SELECT name, occupation FROM users WHERE userid IN (199, 200, 207) BYPASS CACHE USING TIMEOUT 200ms;
+
+``USING TIMEOUT`` is a Scylla CQL extension and not part of Apache Cassandra CQL.
+
+.. _like-operator:
+
+LIKE Operator
+~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+The ``LIKE`` operation on ``SELECT`` statements informs Scylla that you are looking for a pattern match. The expression ‘column LIKE pattern’ yields true only if the entire column value matches the pattern.
+
+The search pattern is a string of characters with two wildcards, as shown:
+
+* ``_`` matches any single character
+* ``%`` matches any substring (including an empty string)
+* ``\`` escapes the next pattern character, so it matches verbatim
+* any other pattern character matches itself
+* an empty pattern matches empty text fields
+
+
+.. note:: Only string types (ascii, text, and varchar) are valid for matching
+
+Currently, the match is **case sensitive**. The entire column value must match the pattern.
+For example, consider the search pattern 'M%n' - this will match ``Martin``, but will not match ``Moonbeam`` because the ``m`` at the end isn't matched. In addition, ``moon`` is not matched because ``M`` is not the same as ``m``. Both the pattern and the column value are assumed to be UTF-8 encoded.
+
+A query can find all values containing some text fragment by matching to an appropriate ``LIKE`` pattern.
+
+**Differences Between Scylla and Cassandra LIKE Operators**
+
+* In Apache Cassandra, you must create a SASI index to use LIKE. Scylla supports LIKE as a regular filter.
+* Consequently, Scylla LIKE will be less performant than Apache Cassandra LIKE for some workloads.
+* Scylla treats underscore (_) as a wildcard; Cassandra doesn't.
+* Scylla treats percent (%) as a wildcard anywhere in the pattern; Cassandra only at the beginning/end
+* Scylla interprets backslash (\\) as an escape character; Cassandra doesn't.
+* Cassandra allows case-insensitive LIKE; Scylla doesn't (see `#4911 <https://github.com/scylladb/scylla/issues/4911>`_).
+* Scylla allows empty LIKE pattern; Cassandra doesn't.
+
+**Example A**
+
+In this example, ``LIKE`` specifies that the match is looking for a word that starts with the letter ``S``. The ``%`` after the letter ``S`` matches any text to the end of the field.
+
+.. code-block:: none
+
+ SELECT * FROM pet_owners WHERE firstname LIKE ‘S%’ ALLOW FILTERING;
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │1 │Adams │Steven │
+ ├──────────┼─────────────────────┼────────────────┤
+ │15 │Erg │Sylvia │
+ ├──────────┼─────────────────────┼────────────────┤
+ │20 │Goldberg │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │25 │Harris │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │88 │Rosenberg │Samuel │
+ ├──────────┼─────────────────────┼────────────────┤
+ │98 │Smith │Sara │
+ ├──────────┼─────────────────────┼────────────────┤
+ │115 │Williams │Susan │
+ ├──────────┼─────────────────────┼────────────────┤
+ │130 │Young │Stuart │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+
+
+
+**Example B**
+
+In this example, you are searching for all pet owners whose last name contains the characters 'erg'.
+
+.. code-block:: none
+
+ SELECT * FROM pet_owners WHERE lastname LIKE ‘%erg%’ ALLOW FILTERING;
+
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │11 │Berger │David │
+ ├──────────┼─────────────────────┼────────────────┤
+ │18 │Gerg │Lawrence │
+ ├──────────┼─────────────────────┼────────────────┤
+ │20 │Goldberg │Stephanie │
+ ├──────────┼─────────────────────┼────────────────┤
+ │88 │Rosenberg │Samuel │
+ ├──────────┼─────────────────────┼────────────────┤
+ │91 │Schulberg │Barry │
+ ├──────────┼─────────────────────┼────────────────┤
+ │110 │Weinberg │Stuart │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+Note that this query does not return:
+
+.. code-block:: none
+
+ ╭──────────┬─────────────────────┬────────────────╮
+ │ID │LastName │FirstName │
+ ├──────────┼─────────────────────┼────────────────┤
+ │15 │Erg │Sylvia │
+ ╰──────────┴─────────────────────┴────────────────╯
+
+As it is case sensitive.
+
+
+**Example C**
+
+This table contains some commonly used ``LIKE`` filters and the matches you can expect the filter to return.
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Filter
+ - Matches
+ * - %abe%
+ - Babel, aberration, cabernet, scarabees
+ * - _0\%
+ - 10%, 20%, 50%
+ * - a%t
+ - asphalt, adapt, at
+
+.. _insert-statement:
+
+INSERT
+^^^^^^
+
+Inserting data for a row is done using an ``INSERT`` statement:
+
+.. code-block::
+
+ insert_statement: INSERT INTO table_name ( `names_values` | `json_clause` )
+ : [ IF NOT EXISTS ]
+ : [ USING `update_parameter` ( AND `update_parameter` )* ];
+ names_values: `names` VALUES `tuple_literal`
+ json_clause: JSON `string` [ DEFAULT ( NULL | UNSET ) ]
+ names: '(' `column_name` ( ',' `column_name` )* ')'
+ update_parameter: ( TIMESTAMP `int_value` | TTL `int_value` | TIMEOUT `duration` )
+ int_value: ( `integer` | `bind_marker` )
+
+For example:
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor, year)
+ VALUES ('Serenity', 'Joss Whedon', 'Nathan Fillion', 2005)
+ USING TTL 86400 IF NOT EXISTS;
+
+The ``INSERT`` statement writes one or more columns for a given row in a table. Note that since a row is identified by
+its ``PRIMARY KEY``, at least the columns composing it must be specified. The list of columns to insert to must be
+supplied when using the ``VALUES`` syntax.
+
+Note that unlike in SQL, ``INSERT`` does not check the prior existence of the row by default: the row is created if none
+existed before, and updated otherwise. Furthermore, there is no means to know which of creation or update happened.
+
+All updates of an ``INSERT`` are applied atomically, meaning the
+statement can not have a partial effect on database state.
+
+It can, however, leave some of the columns unchanged due to the semantics
+of eventual consistency on an event of a timestamp collision:
+
+``INSERT`` statements happening concurrently at different cluster
+nodes proceed without coordination. Eventually cell values
+supplied by a statement with the highest timestamp will prevail.
+
+Unless a timestamp is provided by the client, Scylla will automatically
+generate a timestamp with microsecond precision for each
+column assigned by ``INSERT``. Scylla ensures timestamps created
+by the same node are unique. Timestamps assigned at different
+nodes are not guaranteed to be globally unique.
+With a steadily high write rate timestamp collision
+is not unlikely. If it happens, i.e. two ``INSERTS`` have the same
+timestamp, the lexicographically bigger value prevails:
+
+Please refer to the :ref:`UPDATE <update-parameters>` section for more information on the :token:`update_parameter`.
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Anonymous', 'Unknown')
+ USING TIMESTAMP 1442880000000000;
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Joseph Whedon', 'Nathan Fillion')
+ USING TIMESTAMP 1442880000000000;
+
+ SELECT movie, director, main_actor FROM NerdMovies WHERE movie = 'Serenity'
+
+.. code-block:: none
+
+ movie | director | main_actor | year
+ ----------+---------------+------------+------
+ Serenity | Joseph Whedon | Unknown | null
+
+
+``INSERT`` is not required to assign all columns, so if two
+statements modify the same primary key but assign different
+columns effects of both statements are preserved:
+
+.. code-block:: cql
+
+ INSERT INTO NerdMovies (movie, director, main_actor)
+ VALUES ('Serenity', 'Joss Whedon', 'Nathan Fillion');
+ INSERT INTO NerdMovies (movie, director, main_actor, year)
+ VALUES ('Serenity', 'Josseph Hill Whedon', 2005);
+ SELECT * FROM NerdMovies WHERE movie = 'Serenity'
+
+.. code-block:: none
+
+ ╭─────────┬───────────────────┬──────────────┬─────╮
+ │movie │director │main_actor │year │
+ ├─────────┼───────────────────┼──────────────┼─────┤
+ │Serenity │Joseph Hill Whedon │Nathan Fillion│2005 │
+ ╰─────────┴───────────────────┴──────────────┴─────╯
+
+Also note that ``INSERT`` does not support counters, while ``UPDATE`` does.
+
+.. note:: New in Scylla Open Source 3.2, you can use the ``IF NOT EXISTS`` condition with the ``INSERT`` statement. When this is used, the insert is only made if the row does not exist prior to the insertion. Each such ``INSERT`` gets a globally unique timestamp. Using ``IF NOT EXISTS`` incurs a non-negligible performance cost (internally, as Paxos will be used), so use ``IF NOT EXISTS`` wisely.
+
+
+Starting with Scylla Open Source 3.2, if :ref:`enabled <cdc-options>` on a table, you can use UPDATE, INSERT, and DELETE statements with Change Data Capture (CDC) tables. Note that this feature is :ref:`experimental <yaml_enabling_experimental_features>` in version 3.2.
+
+.. to-do - add link to cdc doc
+
+.. _update-statement:
+
+UPDATE
+^^^^^^
+
+Updating a row is done using an ``UPDATE`` statement:
+
+.. code-block::
+
+ update_statement: UPDATE `table_name`
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : SET `assignment` ( ',' `assignment` )*
+ : WHERE `where_clause`
+ : [ IF ( EXISTS | `condition` ( AND `condition` )*) ]
+ update_parameter: ( TIMESTAMP `int_value` | TTL `int_value` | TIMEOUT `duration` )
+ int_value: ( `integer` | `bind_marker` )
+ assignment: `simple_selection` '=' `term`
+ : | `column_name` '=' `column_name` ( '+' | '-' ) `term`
+ : | `column_name` '=' `list_literal` '+' `column_name`
+ simple_selection: `column_name`
+ : | `column_name` '[' `term` ']'
+ : | `column_name` '.' `field_name`
+ condition: `simple_selection` `operator` `term`
+
+For instance:
+
+.. code-block:: cql
+
+ UPDATE NerdMovies USING TTL 400
+ SET director = 'Joss Whedon',
+ main_actor = 'Nathan Fillion',
+ year = 2005
+ WHERE movie = 'Serenity';
+
+ UPDATE UserActions
+ SET total = total + 2
+ WHERE user = B70DE1D0-9908-4AE3-BE34-5573E5B09F14
+ AND action = 'click';
+
+The ``UPDATE`` statement writes one or more columns for a given row in a table. The :token:`where_clause` is used to
+select the row to update and must include all columns composing the ``PRIMARY KEY``. Non-primary key columns are then
+set using the ``SET`` keyword.
+
+Note that unlike in SQL, ``UPDATE`` does not check the prior existence of the row by default,
+
+(except through IF_, see below):
+
+the row is created if none existed before, and updated otherwise. Furthermore, there is no way to know
+whether creation or update occurred.
+
+In an ``UPDATE`` statement, all updates within the same partition key are applied atomically,
+meaning either all provided values are stored or none at all.
+
+Similarly to ``INSERT``, ``UPDATE`` statement happening concurrently at different
+cluster nodes proceed without coordination. Cell values
+supplied by a statement with the highest timestamp will prevail.
+If two ``UPDATE`` statements or ``UPDATE`` and ``INSERT``
+statements have the same timestamp,
+lexicographically bigger value prevails.
+
+Regarding the :token:`assignment`:
+
+- ``c = c + 3`` is used to increment/decrement counters. The column name after the '=' sign **must** be the same as
+ the one before the '=' sign. Note that increment/decrement is only allowed on counters, and are the *only* update
+ operations allowed on counters. See the section on :ref:`counters <counters>` for details.
+- ``id = id + <some-collection>`` and ``id[value1] = value2`` are for collections, see the :ref:`relevant section
+ <collections>` for details.
+- ``id.field = 3`` is for setting the value of a field on non-frozen user-defined types.
+
+.. _IF:
+
+IF condition
+~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+It is, however, possible to use the conditions on some columns through ``IF``, in which case the row will not be updated
+unless the conditions are met. Each such ``UPDATE`` gets a globally unique timestamp.
+But, please note that using ``IF`` conditions will incur a non-negligible performance
+cost (internally, Paxos will be used), so this should be used sparingly.
+
+
+.. _update-parameters:
+
+Update parameters
+~~~~~~~~~~~~~~~~~
+
+The ``UPDATE``, ``INSERT`` (and ``DELETE`` and ``BATCH`` for the ``TIMESTAMP``) statements support the following
+parameters:
+
+- ``TIMESTAMP``: sets the timestamp for the operation. If not specified, the coordinator will use the current time, in
+ *microseconds* since the `Unix epoch <https://en.wikipedia.org/wiki/Unix_time>`_ (January 1st 1970 at 00:00:00 UTC),
+ at the start of statement execution as the timestamp. This is usually a suitable default.
+ :ref:`INSERT <insert-statement>`, :ref:`UPDATE <update-statement>`, :ref:`DELETE <delete_statement>`, or :ref:`BATCH <batch_statement>`
+ statements ``USING TIMESTAMP`` should provide a unique timestamp value, similar to the one
+ implicitly set by the coordinator by default, when the `USING TIMESTAMP` update parameter is absent.
+ Scylla ensures that query timestamps created by the same coordinator node are unique (even across different shards
+ on the same node). However, timestamps assigned at different nodes are not guaranteed to be globally unique.
+ Note that with a steadily high write rate, timestamp collision is not unlikely. If it happens, e.g. two INSERTS
+ have the same timestamp, conflicting cell values are compared and the cells with the lexicographically bigger value prevail.
+- ``TTL``: specifies an optional Time To Live (in seconds) for the inserted values. If set, the inserted values are
+ automatically removed from the database after the specified time. Note that the TTL concerns the inserted values, not
+ the columns themselves. This means that any subsequent update of the column will also reset the TTL (to whatever TTL
+ is specified in that update). By default, values never expire. A TTL of 0 is equivalent to no TTL. If the table has a
+ default_time_to_live, a TTL of 0 will remove the TTL for the inserted or updated values. A TTL of ``null`` is equivalent
+ to inserting with a TTL of 0. You can read more about TTL in the :doc:`documentation </getting-started/time-to-live>` and also in `this Scylla University lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`.
+- ``TIMEOUT``: specifies a timeout duration for the specific request.
+ Please refer to the :ref:`SELECT <using-timeout>` section for more information.
+
+.. _delete_statement:
+
+DELETE
+^^^^^^
+
+Deleting rows or parts of rows uses the ``DELETE`` statement:
+
+.. code-block::
+
+ delete_statement: DELETE [ `simple_selection` ( ',' `simple_selection` ) ]
+ : FROM `table_name`
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : WHERE `where_clause`
+ : [ IF ( EXISTS | `condition` ( AND `condition` )* ) ]
+
+For instance:
+
+.. code-block:: cql
+
+ DELETE FROM NerdMovies USING TIMESTAMP 1240003134000000
+ WHERE movie = 'Serenity';
+
+ DELETE phone FROM Users
+ WHERE userid IN (C73DE1D3-AF08-40F3-B124-3FF3E5109F22, B70DE1D0-9908-4AE3-BE34-5573E5B09F14);
+
+The ``DELETE`` statement deletes columns and rows. If column names are provided directly after the ``DELETE`` keyword,
+only those columns are deleted from the row indicated by the ``WHERE`` clause. Otherwise, whole rows are removed.
+
+The ``WHERE`` clause specifies which rows are to be deleted. Multiple rows may be deleted with one statement by using an
+``IN`` operator. A range of rows may be deleted using an inequality operator (such as ``>=``).
+
+``DELETE`` supports the ``TIMESTAMP`` option with the same semantics as the TIMESTAMP parameter used in the ``UPDATE`` statement.
+The ``DELETE`` statement deletes data written with :ref:`INSERT <insert-statement>` or :ref:`UPDATE <update-statement>` (or :ref:`BATCH <batch_statement>`)
+using a timestamp that is less than or equal to the ``DELETE`` timestamp.
+For more information on the :token:`update_parameter` refer to the :ref:`UPDATE <update-parameters>` section.
+
+In a ``DELETE`` statement, all deletions within the same partition key are applied atomically,
+meaning either all columns mentioned in the statement are deleted or none.
+If ``DELETE`` statement has the same timestamp as ``INSERT`` or
+``UPDATE`` of the same primary key, delete operation prevails.
+
+A ``DELETE`` operation can be conditional through the use of an ``IF`` clause, similar to ``UPDATE`` and ``INSERT``
+statements. Each such ``DELETE`` gets a globally unique timestamp.
+However, as with ``INSERT`` and ``UPDATE`` statements, this will incur a non-negligible performance cost
+(internally, Paxos will be used) and so should be used sparingly.
+
+
+Range deletions
+~~~~~~~~~~~~~~~
+
+Range deletions allow you to delete rows from a single partition, given that the clustering key is within the given range. The delete request can be determined on both ends, or it can be open-ended.
+
+.. _open-range-deletions:
+
+
+Open range deletions
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2 Scylla Open Source
+
+Open range deletions delete rows based on an open-ended request (>, <, >=, =<, etc.)
+
+For example, suppose your data set for events at Madison Square Garden includes:
+
+
+.. code-block:: none
+
+ CREATE KEYSPACE mykeyspace WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} AND durable_writes = true;
+ use mykeyspace ;
+ CREATE TABLE events ( id text, created_at date, content text, PRIMARY KEY (id, created_at) );
+
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-11-19', 'SuperM');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-11-15', 'Billy Joel');
+ INSERT into events (id, created_at, content) VALUES ('game', '2019-11-03', 'Knicks v Sacramento');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-10-31', 'Dead & Company');
+ INSERT into events (id, created_at, content) VALUES ('game', '2019-10-28', 'Knicks v Chicago');
+ INSERT into events (id, created_at, content) VALUES ('concert', '2019-10-25', 'Billy Joel');
+
+
+ SELECT * from events;
+
+ id | created_at | content
+ ---------+------------+---------------------
+ game | 2019-10-28 | Knicks v Chicago
+ game | 2019-11-03 | Knicks v Sacramento
+ concert | 2019-10-25 | Billy Joel
+ concert | 2019-10-31 | Dead & Company
+ concert | 2019-11-15 | Billy Joel
+ concert | 2019-11-19 | SuperM
+
+ (6 rows)
+
+And you wanted to delete all of the concerts from the month of October using an open-ended range delete. You would run:
+
+.. code-block:: none
+
+ DELETE FROM events WHERE id='concert' AND created_at <= '2019-10-31';
+
+ SELECT * from events;
+
+ id | created_at | content
+ ---------+------------+---------------------
+ game | 2019-10-28 | Knicks v Chicago
+ game | 2019-11-03 | Knicks v Sacramento
+ concert | 2019-11-15 | Billy Joel
+ concert | 2019-11-19 | SuperM
+
+ (4 rows)
+
+.. _batch_statement:
+
+BATCH
+^^^^^
+
+Multiple ``INSERT``, ``UPDATE`` and ``DELETE`` can be executed in a single statement by grouping them through a
+``BATCH`` statement:
+
+.. code-block::
+
+ batch_statement: BEGIN [ UNLOGGED | COUNTER ] BATCH
+ : [ USING `update_parameter` ( AND `update_parameter` )* ]
+ : `modification_statement` ( ';' `modification_statement` )*
+ : APPLY BATCH
+ modification_statement: `insert_statement` | `update_statement` | `delete_statement`
+
+For instance:
+
+.. code-block:: cql
+
+ BEGIN BATCH
+ INSERT INTO users (userid, password, name) VALUES ('user2', 'ch@ngem3b', 'second user');
+ UPDATE users SET password = 'ps22dhds' WHERE userid = 'user3';
+ INSERT INTO users (userid, password) VALUES ('user4', 'ch@ngem3c');
+ DELETE name FROM users WHERE userid = 'user1';
+ APPLY BATCH;
+
+The ``BATCH`` statement group multiple modification statements (insertions/updates and deletions) into a single
+statement. It serves several purposes:
+
+- It saves network round-trips between the client and the server (and sometimes between the server coordinator and the
+ replicas) when batching multiple updates.
+- All updates in a ``BATCH`` belonging to a given partition key are performed atomically.
+- By default, all operations in the batch are performed as *logged*, to ensure all mutations eventually complete (or
+ none will). See the notes on :ref:`UNLOGGED batches <unlogged-batches>` for more details.
+
+Note that:
+
+- ``BATCH`` statements may only contain ``UPDATE``, ``INSERT`` and ``DELETE`` statements (not other batches, for instance).
+- Batches are *not* a full analogue for SQL transactions.
+- If a timestamp is not specified for each operation, then all operations will be applied with the same timestamp
+ (either one generated automatically, or the timestamp provided at the batch level). Due to Scylla's conflict
+ resolution procedure in the case of timestamp ties, operations may be applied in an order that is different from the order they are listed in the ``BATCH`` statement. To force a
+ particular operation ordering, you must specify per-operation timestamps.
+- A LOGGED batch to a single partition will be converted to an UNLOGGED batch as an optimization.
+
+``BATCH`` supports the ``TIMESTAMP`` option with the same semantics as the TIMESTAMP parameter in ``UPDATE`` statement.
+For more information on the :token:`update_parameter` refer to the :ref:`UPDATE <update-parameters>` section.
+
+.. _unlogged-batches:
+
+``UNLOGGED`` batches
+~~~~~~~~~~~~~~~~~~~~
+
+By default, Scylla uses a batch log to ensure all operations in a batch eventually complete or none will (note,
+however, that operations are only isolated within a single partition).
+
+There is a performance penalty for batch atomicity when a batch spans multiple partitions. If you do not want to incur
+this penalty, you can tell Scylla to skip the batchlog with the ``UNLOGGED`` option. If the ``UNLOGGED`` option is
+used, a failed batch might leave the patch only partly applied.
+
+``COUNTER`` batches
+~~~~~~~~~~~~~~~~~~~
+
+Use the ``COUNTER`` option for batched counter updates. Unlike other
+updates in Scylla, counter updates are not idempotent.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
diff --git a/docs/getting-started/functions.rst b/docs/getting-started/functions.rst
--- a/docs/getting-started/functions.rst
+++ b/docs/getting-started/functions.rst
@@ -0,0 +1,291 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _cql-functions:
+
+.. Need some intro for UDF and native functions in general and point those to it.
+.. _udfs:
+.. _native-functions:
+
+Functions
+---------
+
+CQL supports two main categories of functions:
+
+- The :ref:`scalar functions <scalar-functions>`, which simply take a number of values and produce an output with it.
+- The :ref:`aggregate functions <aggregate-functions>`, which are used to aggregate multiple rows of results from a
+ ``SELECT`` statement.
+
+.. In both cases, CQL provides a number of native "hard-coded" functions as well as the ability to create new user-defined
+.. functions.
+
+.. .. note:: By default, the use of user-defined functions is disabled by default for security concerns (even when
+.. enabled, the execution of user-defined functions is sandboxed and a "rogue" function should not be allowed to do
+.. evil, but no sandbox is perfect so using user-defined functions is opt-in). See the ``enable_user_defined_functions``
+.. in ``scylla.yaml`` to enable them.
+
+.. A function is identifier by its name:
+
+.. .. code-block::
+
+ function_name: [ `keyspace_name` '.' ] `name`
+
+.. _scalar-functions:
+
+Scalar functions
+^^^^^^^^^^^^^^^^
+
+.. _scalar-native-functions:
+
+Native functions
+~~~~~~~~~~~~~~~~
+
+Cast
+````
+
+Supported starting from Scylla version 2.1
+
+The ``cast`` function can be used to convert one native datatype to another.
+
+The following table describes the conversions supported by the ``cast`` function. Scylla will silently ignore any cast converting a cast datatype into its own datatype.
+
+=============== =======================================================================================================
+ From To
+=============== =======================================================================================================
+ ``ascii`` ``text``, ``varchar``
+ ``bigint`` ``tinyint``, ``smallint``, ``int``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``boolean`` ``text``, ``varchar``
+ ``counter`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``,
+ ``text``, ``varchar``
+ ``date`` ``timestamp``
+ ``decimal`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``varint``, ``text``,
+ ``varchar``
+ ``double`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``float`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``inet`` ``text``, ``varchar``
+ ``int`` ``tinyint``, ``smallint``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``smallint`` ``tinyint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``, ``text``,
+ ``varchar``
+ ``time`` ``text``, ``varchar``
+ ``timestamp`` ``date``, ``text``, ``varchar``
+ ``timeuuid`` ``timestamp``, ``date``, ``text``, ``varchar``
+ ``tinyint`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``varint``,
+ ``text``, ``varchar``
+ ``uuid`` ``text``, ``varchar``
+ ``varint`` ``tinyint``, ``smallint``, ``int``, ``bigint``, ``float``, ``double``, ``decimal``, ``text``,
+ ``varchar``
+=============== =======================================================================================================
+
+The conversions rely strictly on Java's semantics. For example, the double value 1 will be converted to the text value
+'1.0'. For instance::
+
+ SELECT avg(cast(count as double)) FROM myTable
+
+Token
+`````
+
+The ``token`` function computes a token for a given partition key. The exact signature of the token function
+depends on the table concerned and on the partitioner used by the cluster.
+
+The arguments of the ``token`` depend on the type of the partition key columns that are used. The return type depends on
+the partitioner in use:
+
+- For Murmur3Partitioner, the return type is ``bigint``.
+
+For instance, in a cluster using the default Murmur3Partitioner, if a table is defined by::
+
+ CREATE TABLE users (
+ userid text PRIMARY KEY,
+ username text,
+ )
+
+The ``token`` function accepts single argument of type ``text`` (in that case, the partition key is ``userid``
+(there are no clustering columns, so the partition key is the same as the primary key)), and the return type will be
+``bigint``.
+
+Uuid
+````
+The ``uuid`` function takes no parameters and generates a random type 4 uuid suitable for use in ``INSERT`` or
+``UPDATE`` statements.
+
+.. _timeuuid-functions:
+
+.. Timeuuid functions
+.. ``````````````````
+
+.. ``now``
+.. #######
+
+.. The ``now`` function takes no arguments and generates, on the coordinator node, a new unique timeuuid at the
+.. time the function is invoked. Note that this method is useful for insertion but is largely non-sensical in
+.. ``WHERE`` clauses. For instance, a query of the form::
+
+.. SELECT * FROM myTable WHERE t = now()
+
+.. will never return any result by design, since the value returned by ``now()`` is guaranteed to be unique.
+
+.. ``currentTimeUUID`` is an alias of ``now``.
+
+.. ``minTimeuuid`` and ``maxTimeuuid``
+.. ###################################
+
+.. The ``minTimeuuid`` (resp. ``maxTimeuuid``) function takes a ``timestamp`` value ``t`` (which can be `either a timestamp
+.. or a date string <timestamps>`) and return a *fake* ``timeuuid`` corresponding to the *smallest* (resp. *biggest*)
+.. possible ``timeuuid`` having for timestamp ``t``. So for instance::
+
+.. SELECT * FROM myTable
+.. WHERE t > maxTimeuuid('2013-01-01 00:05+0000')
+.. AND t < minTimeuuid('2013-02-02 10:00+0000')
+
+.. will select all rows where the ``timeuuid`` column ``t`` is strictly older than ``'2013-01-01 00:05+0000'`` but strictly
+.. younger than ``'2013-02-02 10:00+0000'``. Please note that ``t >= maxTimeuuid('2013-01-01 00:05+0000')`` would still
+.. *not* select a ``timeuuid`` generated exactly at '2013-01-01 00:05+0000' and is essentially equivalent to ``t >
+.. maxTimeuuid('2013-01-01 00:05+0000')``.
+
+.. note:: We called the values generated by ``minTimeuuid`` and ``maxTimeuuid`` *fake* UUID because they do no respect
+ the Time-Based UUID generation process specified by the `RFC 4122 <http://www.ietf.org/rfc/rfc4122.txt>`__. In
+ particular, the value returned by these two methods will not be unique. This means you should only use those methods
+ for querying (as in the example above). Inserting the result of those methods is almost certainly *a bad idea*.
+
+Datetime functions
+``````````````````
+
+.. versionadded:: 2.3
+
+Retrieving the current date/time
+################################
+
+The following functions can be used to retrieve the date/time at the time where the function is invoked:
+
+===================== ===============
+Function name Output type
+===================== ===============
+``currentTimestamp`` ``timestamp``
+``currentDate`` ``date``
+``currentTime`` ``time``
+``currentTimeUUID`` ``timeUUID``
+===================== ===============
+
+For example, to retrieve data up to today, run the following query::
+
+ SELECT * FROM myTable WHERE date >= currentDate()
+
+Time conversion functions
+#########################
+
+A number of functions are provided to “convert” a ``timeuuid``, a ``timestamp``, or a ``date`` into another ``native``
+type.
+
+===================== =============== ===================================================================
+Function name Input type Description
+===================== =============== ===================================================================
+``toDate`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``date`` type
+``toDate`` ``timestamp`` Converts the ``timestamp`` argument into a ``date`` type
+``toTimestamp`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``timestamp`` type
+``toTimestamp`` ``date`` Converts the ``date`` argument into a ``timestamp`` type
+``toUnixTimestamp`` ``timeuuid`` Converts the ``timeuuid`` argument into a ``bigInt`` raw value
+``toUnixTimestamp`` ``timestamp`` Converts the ``timestamp`` argument into a ``bigInt`` raw value
+``toUnixTimestamp`` ``date`` Converts the ``date`` argument into a ``bigInt`` raw value
+``dateOf`` ``timeuuid`` Similar to ``toTimestamp(timeuuid)`` (DEPRECATED)
+``unixTimestampOf`` ``timeuuid`` Similar to ``toUnixTimestamp(timeuuid)`` (DEPRECATED)
+===================== =============== ===================================================================
+
+.. Blob conversion functions
+.. `````````````````````````
+.. A number of functions are provided to “convert” the native types into binary data (``blob``). For every
+.. ``<native-type>`` ``type`` supported by CQL (a notable exceptions is ``blob``, for obvious reasons), the function
+.. ``typeAsBlob`` takes a argument of type ``type`` and return it as a ``blob``. Conversely, the function ``blobAsType``
+.. takes a 64-bit ``blob`` argument and convert it to a ``bigint`` value. And so for instance, ``bigintAsBlob(3)`` is
+.. ``0x0000000000000003`` and ``blobAsBigint(0x0000000000000003)`` is ``3``.
+
+
+Blob conversion functions
+`````````````````````````
+A number of functions are provided to “convert” the native types into binary data (``blob``). For every
+``<native-type>`` ``type`` supported by CQL (a notable exception is a ``blob``, for obvious reasons), the function
+``typeAsBlob`` takes an argument of type ``type`` and returns it as a ``blob``. Conversely, the function ``blobAsType``
+takes a 64-bit ``blob`` argument and converts it to a ``bigint`` value. For example, ``bigintAsBlob(3)`` is
+``0x0000000000000003`` and ``blobAsBigint(0x0000000000000003)`` is ``3``.
+
+.. _aggregate-functions:
+
+Aggregate functions
+^^^^^^^^^^^^^^^^^^^
+
+Aggregate functions work on a set of rows. They receive values for each row and return one value for the whole set.
+
+If ``normal`` columns, ``scalar functions``, ``UDT`` fields, ``writetime``, or ``ttl`` are selected together with
+aggregate functions, the values returned for them will be the ones of the first row matching the query.
+
+.. note::
+ The ``LIMIT`` and ``PER PARTITION LIMIT`` used in the ``SELECT`` query will have no effect if the limit is greater
+ than or equal to 1 because they are applied to the output of the aggregate functions (which return one value for
+ the whole set of rows).
+
+
+Native aggregates
+~~~~~~~~~~~~~~~~~
+
+.. _count-function:
+
+Count
+`````
+
+The ``count`` function can be used to count the rows returned by a query. Example::
+
+ SELECT COUNT (*) FROM plays;
+ SELECT COUNT (1) FROM plays;
+
+It also can be used to count the non-null value of a given column::
+
+ SELECT COUNT (scores) FROM plays;
+
+Max and Min
+```````````
+
+The ``max`` and ``min`` functions can be used to compute the maximum and the minimum value returned by a query for a
+given column. For instance::
+
+ SELECT MIN (players), MAX (players) FROM plays WHERE game = 'quake';
+
+Sum
+```
+
+The ``sum`` function can be used, to sum up all the values returned by a query for a given column. For instance::
+
+ SELECT SUM (players) FROM plays;
+
+Avg
+```
+
+The ``avg`` function can be used to compute the average of all the values returned by a query for a given column. For
+instance::
+
+ SELECT AVG (players) FROM plays;
+
+.. _user-defined-aggregates-functions:
+
+.. include:: /rst_include/apache-cql-return-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/images/checkmark-16.png b/docs/getting-started/images/checkmark-16.png
--- a/docs/getting-started/images/checkmark-16.png
+++ b/docs/getting-started/images/checkmark-16.png
null
diff --git a/docs/getting-started/images/x-mark-16.png b/docs/getting-started/images/x-mark-16.png
--- a/docs/getting-started/images/x-mark-16.png
+++ b/docs/getting-started/images/x-mark-16.png
null
diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst
--- a/docs/getting-started/index.rst
+++ b/docs/getting-started/index.rst
@@ -0,0 +1,65 @@
+Getting Started
+===============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ install-scylla/index
+ configure
+ requirements
+ cql
+ cqlsh
+ Scylla Drivers </using-scylla/drivers/index>
+ Migrate to Scylla </using-scylla/migrate-scylla>
+ Integration Solutions </using-scylla/integrations/index>
+ tutorials
+
+.. panel-box::
+ :title: Scylla Requirements
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla System Requirements Guide</getting-started/system-requirements/>`
+ * :doc:`OS Support by Platform and Version</getting-started/os-support/>`
+
+.. panel-box::
+ :title: Install and Configure Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * `Install Scylla (Binary Packages, Docker, or EC2) <https://www.scylladb.com/download/>`_ - Links to the ScyllaDB Download Center
+
+ * :doc:`Configure Scylla</getting-started/system-configuration/>`
+ * :doc:`Run Scylla in a Shared Environment </getting-started/scylla-in-a-shared-environment>`
+ * :doc:`Create a Scylla Cluster - Single Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster/>`
+ * :doc:`Create a Scylla Cluster - Multi Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster-multidc/>`
+
+.. panel-box::
+ :title: Develop Applications for Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Drivers</using-scylla/drivers/index>`
+ * `Get Started Lesson on Scylla University <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/quick-wins-install-and-run-scylla/>`_
+ * :doc:`Apache Cassandra Query Language (CQL) Reference </getting-started/cql/>`
+ * :doc:`CQLSh: the CQL shell</getting-started/cqlsh/>`
+
+.. panel-box::
+ :title: Use Scylla with Third-party Solutions
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Migrate to Scylla </using-scylla/migrate-scylla>` - How to migrate your current database to Scylla
+ * :doc:`Integrate with Scylla </using-scylla/integrations/index>` - Integration solutions with Scylla
+
+
+.. panel-box::
+ :title: Tutorials
+ :id: "getting-started"
+ :class: my-panel
+
+ The tutorials will show you how to use ScyllaDB as a data source for an application.
+
+ * `Build an IoT App with sensor simulator and a REST API <https://care-pet.docs.scylladb.com/>`_ - ScyllaDB Tutorial
+ * `Implement CRUD operations with a TODO App <https://github.com/scylladb/scylla-cloud-getting-started/>`_ - ScyllaDB Cloud Tutorial
diff --git a/docs/getting-started/install-scylla/air-gapped-install.rst b/docs/getting-started/install-scylla/air-gapped-install.rst
--- a/docs/getting-started/install-scylla/air-gapped-install.rst
+++ b/docs/getting-started/install-scylla/air-gapped-install.rst
@@ -0,0 +1,11 @@
+==============================
+Air-gapped Server Installation
+==============================
+
+An air-gapped server is a server without any access to external repositories or connections to any network, including the internet.
+To install Scylla on an air-gapped server, you first need to download the relevant files from a server that is not air-gapped and then and move the files to the air-gapped servers to complete the installation.
+
+There are two ways to install Scylla on an air-gapped server:
+
+- With root privileges (recommended): download the OS specific packages (rpms and debs) and install them with the package manager (dnf and apt). See `Install Scylla on an Air-gapped Server Using the Packages (Option 2) <https://www.scylladb.com/download/?platform=tar>`_.
+- Without root privileges: using the :doc:`Scylla Unified Installer <unified-installer>`.
diff --git a/docs/getting-started/install-scylla/config-commands.rst b/docs/getting-started/install-scylla/config-commands.rst
--- a/docs/getting-started/install-scylla/config-commands.rst
+++ b/docs/getting-started/install-scylla/config-commands.rst
@@ -0,0 +1,69 @@
+==============================
+Scylla Configuration Reference
+==============================
+
+This guide describes the commands that you can use to configure your Scylla clusters.
+The commands are all sent via the command line in a terminal and sudo or root access is not required as long as you have permission to execute in the directory.
+
+.. caution:: You should **only** use configuration settings which are officially supported.
+
+A list of all Scylla commands can be obtained by running
+
+.. code-block:: none
+
+ scylla --help
+
+.. note:: This command displays all Scylla commands as well as Seastar commands. The Seastar commands are listed as Core Options.
+
+For example:
+
+.. code-block:: none
+
+ Scylla version 4.2.3-0.20210104.24346215c2 with build-id 0c8faf8bb8a3a0eda9337aad98ed3a6d814a4fa9 starting ...
+ command used: "scylla --help"
+ parsed command line options: [help]
+ Scylla options:
+ -h [ --help ] show help message
+ --version print version number and exit
+ --options-file arg configuration file (i.e.
+ <SCYLLA_HOME>/conf/scylla.yaml)
+ --memtable-flush-static-shares arg If set to higher than 0, ignore the
+ controller's output and set the
+ memtable shares statically. Do not set
+ this unless you know what you are doing
+ and suspect a problem in the
+ controller. This option will be retired
+ when the controller reaches more
+ maturity
+ --compaction-static-shares arg If set to higher than 0, ignore the
+ controller's output and set the
+ compaction shares statically. Do not
+ set this unless you know what you are
+ doing and suspect a problem in the
+ controller. This option will be retired
+ when the controller reaches more
+ maturity
+
+.. note:: This is an incomplete screenshot. For the complete file, run the command in a terminal.
+
+Scylla Configuration Files and Scylla Commands
+----------------------------------------------
+
+Some Scylla Command Line commands are derived from the `scylla.yaml <https://github.com/scylladb/scylla/blob/master/conf/scylla.yaml>`_ configuration parameters.
+
+For example, in the case of ``cluster_name: 'Test Cluster'`` as seen in the `scylla.yaml <https://github.com/scylladb/scylla/blob/master/conf/scylla.yaml>`_ configuration parameters.
+
+To send this configuration setting with the command line, run:
+
+.. code-block:: none
+
+ scylla --cluster-name 'Test Cluster'
+
+
+As you can see from the example above, the general rule of thumb is:
+
+#. Take a configuration parameter from the scylla.yaml file.
+#. Prepend it with ``scylla --``.
+#. In any place where there is an underscore, replace with a dash.
+#. Run the command in a terminal.
+
diff --git a/docs/getting-started/install-scylla/dev-mod.rst b/docs/getting-started/install-scylla/dev-mod.rst
--- a/docs/getting-started/install-scylla/dev-mod.rst
+++ b/docs/getting-started/install-scylla/dev-mod.rst
@@ -0,0 +1,17 @@
+Scylla Developer Mode
+=====================
+
+If you want to use Scylla in developer mode you need to use the command below (using root privileges)
+
+``sudo scylla_dev_mode_setup --developer-mode 1``
+
+
+This script will write the developer mode setting into ``/etc/scylla.d/dev-mode.conf``
+
+
+
+
+
+
+
+
diff --git a/docs/getting-started/install-scylla/disable-housekeeping.rst b/docs/getting-started/install-scylla/disable-housekeeping.rst
--- a/docs/getting-started/install-scylla/disable-housekeeping.rst
+++ b/docs/getting-started/install-scylla/disable-housekeeping.rst
@@ -0,0 +1,21 @@
+
+=========================================
+Scylla Housekeeping and how to disable it
+=========================================
+
+It is always recommended to run the latest version of Scylla Open Source or Scylla Enterprise.
+The latest stable release version is always available from the `Download Center <https://www.scylladb.com/download/>`_.
+
+When you install Scylla, it installs by default two services: **scylla-housekeeping-restart** and **scylla-housekeeping-daily**. These services check for the latest Scylla version and prompt the user if they are using a version that is older than what is publicly available.
+Information about your Scylla deployment, including the Scylla version currently used, as well as unique user and server identifiers, are collected by a centralized service.
+
+To disable these service, update file ``/etc/scylla.d/housekeeping.cfg`` as follow: ``check-version: False``
+
+See also:
+
+* `Scylla privacy <https://www.scylladb.com/privacy/>`_
+* :doc:`Getting Started </getting-started/index>`
+
+
+
+
diff --git a/docs/getting-started/install-scylla/index.rst b/docs/getting-started/install-scylla/index.rst
--- a/docs/getting-started/install-scylla/index.rst
+++ b/docs/getting-started/install-scylla/index.rst
@@ -0,0 +1,37 @@
+Install Scylla
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ scylla-web-installer
+ unified-installer
+ air-gapped-install
+ rpm-info
+ disable-housekeeping
+ dev-mod
+ config-commands
+
+.. panel-box::
+ :title: Install Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ Keep your versions up-to-date. The two latest versions are supported. Also always install the latest patches for your version.
+
+ * Download and install Scylla Server, Drivers and Tools in `Scylla Download Center <https://www.scylladb.com/download/#server/>`_
+ * :doc:`ScyllaDB Web Installer for Linux <scylla-web-installer>`
+ * :doc:`Scylla Unified Installer (relocatable executable) <unified-installer>`
+ * :doc:`Air-gapped Server Installation <air-gapped-install>`
+ * :doc:`What is in each RPM </getting-started/install-scylla/rpm-info/>`
+ * :doc:`Create a Scylla Cluster - Single Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster/>`
+ * :doc:`Create a Scylla Cluster - Multi Data Center (DC) </operating-scylla/procedures/cluster-management/create-cluster-multidc/>`
+ * :doc:`Scylla Developer Mode </getting-started/install-scylla/dev-mod>`
+ * :doc:`Scylla Configuration Command Reference </getting-started/install-scylla/config-commands>`
+ * `Scylla Housekeeping and how to disable it <disable-housekeeping>`_
+
+
+
+
+
diff --git a/docs/getting-started/install-scylla/rpm-info.rst b/docs/getting-started/install-scylla/rpm-info.rst
--- a/docs/getting-started/install-scylla/rpm-info.rst
+++ b/docs/getting-started/install-scylla/rpm-info.rst
@@ -0,0 +1,13 @@
+What is in each RPM
+^^^^^^^^^^^^^^^^^^^
+
+* scylla : Scylla is a highly scalable, eventually consistent, distributed, partitioned row DB. Includes all other packages.
+* scylla-server : The Scylla database server
+* scylla-conf : Scylla configuration package
+* scylla-debuginfo : Debug information for package scylla
+* scylla-jmx : Scylla JMX
+* scylla-kernel-conf : Scylla configuration package for the Linux kernel
+* scylla-machine-image.noarch : Scylla Machine Image
+* scylla-tools.noarch : Scylla Tools, like nodetool, cqlsh, cassandra-stress
+* scylla-tools-core.noarch : Core files for Scylla tools
+* scylla-python3 : A standalone python3 interpreter that can be moved around different Linux machines
diff --git a/docs/getting-started/install-scylla/scylla-web-installer.rst b/docs/getting-started/install-scylla/scylla-web-installer.rst
--- a/docs/getting-started/install-scylla/scylla-web-installer.rst
+++ b/docs/getting-started/install-scylla/scylla-web-installer.rst
@@ -0,0 +1,61 @@
+==================================
+ScyllaDB Web Installer for Linux
+==================================
+
+ScyllaDB Web Installer is a platform-agnostic installation script you can run with ``curl`` to install ScyllaDB on Linux.
+
+See `ScyllaDB Download Center <https://www.scylladb.com/download/#server>`_ for information on manually installing ScyllaDB with platform-specific installation packages.
+
+Prerequisites
+--------------
+
+Ensure that your platform is supported by the ScyllaDB version you want to install.
+See :doc:`OS Support by Platform and Version </getting-started/os-support/>`.
+
+Installing ScyllaDB with Web Installer
+---------------------------------------
+To install ScyllaDB with Web Installer, run:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash
+
+By default, running the script installs the latest official version of ScyllaDB Open Source. You can use the following
+options to install a different version or ScyllaDB Enterprise:
+
+.. list-table::
+ :widths: 20 25 55
+ :header-rows: 1
+
+ * - Option
+ - Acceptable values
+ - Description
+ * - ``--scylla-product``
+ - ``scylla`` | ``scylla-enterprise``
+ - Specifies the ScyllaDB product to install: Open Source (``scylla``) or Enterprise (``scylla-enterprise``) The default is ``scylla``.
+ * - ``--scylla-version``
+ - ``<version number>``
+ - Specifies the ScyllaDB version to install. You can specify the major release (``x.y``) to install the latest patch for that version or a specific patch release (``x.y.x``). The default is the latest official version.
+
+You can run the command with the ``-h`` or ``--help`` flag to print information about the script.
+
+Examples
+---------
+
+Installing ScyllaDB Open Souce 4.6.1:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-version 4.6.1
+
+Installing the latest patch release for ScyllaDB Open Source 4.6:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-version 4.6
+
+Installing ScyllaDB Enterprise 2021.1:
+
+.. code:: console
+
+ curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-product scylla-enterprise --scylla-version 2021.1
diff --git a/docs/getting-started/install-scylla/unified-installer.rst b/docs/getting-started/install-scylla/unified-installer.rst
--- a/docs/getting-started/install-scylla/unified-installer.rst
+++ b/docs/getting-started/install-scylla/unified-installer.rst
@@ -0,0 +1,64 @@
+=================================================
+Scylla Unified Installer (relocatable executable)
+=================================================
+
+This document covers how to install, uninstall, and upgrade using the Scylla Unified Installer. The Unified Installer is recommended to be used when you do not have root privileges to the server.
+If you have root privileges, it is recommended to download the OS specific packages (RPMs and DEBs) and install them with the package manager (dnf and apt).
+
+Supported distros
+=================
+
+* CentOS 7 (Only support root offline install)
+* CentOS 8
+* Ubuntu 18.04 (developer-mode is used if NOFILE rlimit is too low)
+* Debian 10
+
+Download and install
+====================
+
+For installation without root privileges, follow the instructions on `Scylla Download Center <https://www.scylladb.com/download/?platform=tar>`_
+
+Upgrade / Downgrade/ Uninstall
+==============================
+
+.. _unified-installed-upgrade:
+
+Upgrade
+-------
+
+The unified package is based on a binary package; it’s not a RPM / DEB packages, so it doesn’t upgrade or downgrade by yum / apt. Currently, only install.sh of scylla supports the upgrade.
+
+Root install:
+
+.. code:: sh
+
+ ./install.sh --upgrade
+
+Nonroot install
+
+.. code:: sh
+
+ ./install.sh --upgrade --nonroot
+
+.. note:: the installation script does not upgrade scylla-jmx and scylla-tools. You will have to do this separately.
+
+Uninstall
+---------
+
+Root uninstall:
+
+.. code:: sh
+
+ sudo ./uninstall.sh
+
+Nonroot uninstall
+
+.. code:: sh
+
+ ./uninstall.sh --nonroot
+
+
+Downgrade
+---------
+
+To downgrade to your original Scylla version, use the Uninstall_ procedure above and then install the original Scylla packages.
diff --git a/docs/getting-started/json.rst b/docs/getting-started/json.rst
--- a/docs/getting-started/json.rst
+++ b/docs/getting-started/json.rst
@@ -0,0 +1,124 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _cql-json:
+
+JSON Support
+------------
+
+.. versionadded:: 2.3
+
+Scylla introduces JSON support to :ref:`SELECT <select-statement>` and :ref:`INSERT <insert-statement>`
+statements. This support does not fundamentally alter the CQL API (for example, the schema is still enforced). It simply
+provides a convenient way to work with JSON documents.
+
+SELECT JSON
+^^^^^^^^^^^
+
+With ``SELECT`` statements, the ``JSON`` keyword can be used to return each row as a single ``JSON`` encoded map. The
+remainder of the ``SELECT`` statement behavior is the same.
+
+The result map keys are the same as the column names in a normal result set. For example, a statement like ``SELECT JSON
+a, ttl(b) FROM ...`` would result in a map with keys ``"a"`` and ``"ttl(b)"``. However, this is one notable exception:
+for symmetry with ``INSERT JSON`` behavior, case-sensitive column names with upper-case letters will be surrounded with
+double-quotes. For example, ``SELECT JSON myColumn FROM ...`` would result in a map key ``"\"myColumn\""`` (note the
+escaped quotes).
+
+The map values will ``JSON``-encoded representations (as described below) of the result set values.
+
+INSERT JSON
+^^^^^^^^^^^
+
+With ``INSERT`` statements, the new ``JSON`` keyword can be used to enable inserting a ``JSON`` encoded map as a single
+row. The format of the ``JSON`` map should generally match that returned by a ``SELECT JSON`` statement on the same
+table. In particular, case-sensitive column names should be surrounded by double-quotes. For example, to insert into a
+table with two columns named "myKey" and "value", you would do the following::
+
+ INSERT INTO mytable JSON '{ "\"myKey\"": 0, "value": 0}'
+
+By default (or if ``DEFAULT NULL`` is explicitly used), a column omitted from the ``JSON`` map will be set to ``NULL``,
+meaning that any pre-existing value for that column will be removed (resulting in a tombstone being created).
+Alternatively, if the ``DEFAULT UNSET`` directive is used after the value, omitted column values will be left unset,
+meaning that pre-existing values for those columns will be preserved.
+
+
+JSON Encoding of Scylla Data Types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Where possible, Scylla will represent and accept data types in their native ``JSON`` representation. Scylla will
+also accept string representations matching the CQL literal format for all single-field types. For example, floats,
+ints, UUIDs, and dates can be represented by CQL literal strings. However, compound types, such as collections, tuples,
+and user-defined types, must be represented by native ``JSON`` collections (maps and lists) or a JSON-encoded string
+representation of the collection.
+
+The following table describes the encodings that Scylla will accept in ``INSERT JSON`` values (and ``fromJson()``
+arguments) as well as the format Scylla will use when returning data for ``SELECT JSON`` statements (and
+``fromJson()``):
+
+=============== ======================== =============== ==============================================================
+ Type Formats accepted Return format Notes
+=============== ======================== =============== ==============================================================
+ ``ascii`` string string Uses JSON's ``\u`` character escape
+ ``bigint`` integer, string integer String must be valid 64 bit integer
+ ``blob`` string string String should be 0x followed by an even number of hex digits
+ ``boolean`` boolean, string boolean String must be "true" or "false"
+ ``date`` string string Date in format ``YYYY-MM-DD``, timezone UTC
+ ``decimal`` integer, float, string float May exceed 32 or 64-bit IEEE-754 floating point precision in
+ client-side decoder
+ ``double`` integer, float, string float String must be valid integer or float
+ ``float`` integer, float, string float String must be valid integer or float
+ ``inet`` string string IPv4 or IPv6 address
+ ``int`` integer, string integer String must be valid 32 bit integer
+ ``list`` list, string list Uses JSON's native list representation
+ ``map`` map, string map Uses JSON's native map representation
+ ``smallint`` integer, string integer String must be valid 16 bit integer
+ ``set`` list, string list Uses JSON's native list representation
+ ``text`` string string Uses JSON's ``\u`` character escape
+ ``time`` string string Time of day in format ``HH-MM-SS[.fffffffff]``
+ ``timestamp`` integer, string string A timestamp. Strings constant allows to input :ref:`timestamps
+ as dates <timestamps>`. Datestamps with format ``YYYY-MM-DD
+ HH:MM:SS.SSS`` are returned.
+ ``timeuuid`` string string Type 1 UUID. See :token:`constant` for the UUID format
+ ``tinyint`` integer, string integer String must be valid 8 bit integer
+ ``tuple`` list, string list Uses JSON's native list representation
+ ``UDT`` map, string map Uses JSON's native map representation with field names as keys
+ ``uuid`` string string See :token:`constant` for the UUID format
+ ``varchar`` string string Uses JSON's ``\u`` character escape
+ ``varint`` integer, string integer Variable length; may overflow 32 or 64 bit integers in
+ client-side decoder
+=============== ======================== =============== ==============================================================
+
+The fromJson() Function
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``fromJson()`` function may be used similarly to ``INSERT JSON``, but for a single column value. It may only be used
+in the ``VALUES`` clause of an ``INSERT`` statement or as one of the column values in an ``UPDATE``, ``DELETE``, or
+``SELECT`` statement. For example, it cannot be used in the selection clause of a ``SELECT`` statement.
+
+The toJson() Function
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``toJson()`` function may be used similarly to ``SELECT JSON``, but for a single column value. It may only be used
+in the selection clause of a ``SELECT`` statement.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/logging.rst b/docs/getting-started/logging.rst
--- a/docs/getting-started/logging.rst
+++ b/docs/getting-started/logging.rst
@@ -0,0 +1,78 @@
+Logging
+=======
+
+Logging with the systemd journal (CentOS, Amazon AMI, Ubuntu, Debian)
+---------------------------------------------------------------------
+On distributions with systemd, Scylla logs are written to the `systemd journal <http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html>`_. You can retrieve log entries with the `journalctl <http://www.freedesktop.org/software/systemd/man/journalctl.html>`_ command.
+
+Listed below are a few useful examples.
+
+* get logs generated by the "scylla" user:
+
+ .. code-block:: shell
+
+ journalctl _UID=`id -u scylla`
+
+* get logs generated by the "scylla" command:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla
+
+* filter only Scylla logs by priority:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -p err..emerg
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -p warning
+
+* filter only Scylla logs by date:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since="2013-3-16 23:59:59"
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since "2015-01-10" --until "2015-01-11 03:00"`
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla --since yesterday
+
+* filter only Scylla logs since last server boot:
+
+ .. code-block:: shell
+
+ journalctl _COMM=scylla -b
+
+Logging on Ubuntu 14.04
+-----------------------
+On Ubuntu 14.04, Scylla writes its initial boot message into :code:`/var/log/upstart/scylla-server.log`.
+
+After Scylla has started, logs are stored in :code:`/var/log/syslog`. Scylla logs can be filter by creating a :code:`rsyslog` configuration file with the following rule (for example, in :code:`/etc/rsyslog.d/10-scylla.conf`)
+
+.. code-block:: shell
+
+ :syslogtag, startswith, "scylla" /var/log/scylla/scylla.log
+ & ~
+
+And then creating the log file with the correct permissions and restarting the service:
+
+.. code-block:: shell
+
+ install -o syslog -g adm -m 0640 /dev/null /var/log/scylla/scylla.log
+ service rsyslog restart
+
+This will send Scylla only logs to :code:`/var/log/scylla/scylla.log`
+
+Logging on Docker
+-----------------
+Starting from Scylla 1.3, `Scylla Docker <https://hub.docker.com/r/scylladb/scylla/>`_, you should use :code:`docker logs` command to access Scylla server and JMX proxy logs
+
+
+.. include:: /rst_include/advance-index.rst
+
diff --git a/docs/getting-started/mv.rst b/docs/getting-started/mv.rst
--- a/docs/getting-started/mv.rst
+++ b/docs/getting-started/mv.rst
@@ -0,0 +1,184 @@
+
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _materialized-views:
+
+Materialized Views
+------------------
+Production ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.x
+
+.. include:: /rst_include/cql-version-index.rst
+
+
+Materialized views names are defined by:
+
+.. code-block:: cql
+
+ view_name: re('[a-zA-Z_0-9]+')
+
+
+.. _create-materialized-view-statement:
+
+CREATE MATERIALIZED VIEW
+........................
+
+You can create a materialized view on a table using a ``CREATE MATERIALIZED VIEW`` statement:
+
+.. code-block:: cql
+
+ create_materialized_view_statement: CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] `view_name` AS
+ : `select_statement`
+ : PRIMARY KEY '(' `primary_key` ')'
+ : WITH `table_options`
+
+For instance::
+
+ CREATE MATERIALIZED VIEW monkeySpecies_by_population AS
+ SELECT * FROM monkeySpecies
+ WHERE population IS NOT NULL AND species IS NOT NULL
+ PRIMARY KEY (population, species)
+ WITH comment='Allow query by population instead of species';
+
+The ``CREATE MATERIALIZED VIEW`` statement creates a new materialized view. Each view is a set of *rows* that
+corresponds to the rows that are present in the underlying, or base table, as specified in the ``SELECT`` statement. A
+materialized view cannot be directly updated, but updates to the base table will cause corresponding updates in the
+view.
+
+Creating a materialized view has three main parts:
+
+- The :ref:`select statement <mv-select>` that restricts the data included in the view.
+- The :ref:`primary key <mv-primary-key>` definition for the view.
+- The :ref:`options <mv-options>` for the view.
+
+Attempting to create an already existing materialized view will return an error unless the ``IF NOT EXISTS`` option is
+used. If it is used, the statement will be a no-op if the materialized view already exists.
+
+.. _mv-select:
+
+MV Select Statement
+...................
+
+The select statement of a materialized view creation defines which of the base table is included in the view. That
+statement is limited in a number of ways:
+
+- The :ref:`selection <selection-clause>` is limited to those that only select columns of the base table. In other
+ words, you can't use any function (aggregate or not), casting, term, etc. Aliases are also not supported. You can,
+ however, use `*` as a shortcut to selecting all columns. Further, :ref:`static columns <static-columns>` cannot be
+ included in a materialized view (which means ``SELECT *`` isn't allowed if the base table has static columns).
+- The ``WHERE`` clause has the following restrictions:
+
+ - It cannot include any :token:`bind_marker`.
+ - The columns that are not part of the *base table* primary key can only be restricted by an ``IS NOT NULL``
+ restriction. No other restriction is allowed.
+ - As the columns that are part of the *view* primary key cannot be null, they must always be at least restricted by a
+ ``IS NOT NULL`` restriction (or any other restriction, but they must have one).
+ - They can also be restricted by relational operations (=, >, <).
+
+- The SELECT statement cannot include **any** of the following:
+
+ - An :ref:`ordering clause <ordering-clause>`
+ - A :ref:`limit <limit-clause>` clause
+ - An :ref:`ALLOW FILTERING <allow-filtering>` clause.
+
+.. _mv-primary-key:
+
+MV Primary Key
+..............
+
+A view must have a primary key, and that primary key must conform to the following restrictions:
+
+- It must contain all the primary key columns of the base table. This ensures that every row in the view corresponds to
+ exactly one row of the base table.
+- It can only contain a single column that is not a primary key column in the base table.
+
+So, for instance, give the following base table definition::
+
+ CREATE TABLE t (
+ k int,
+ c1 int,
+ c2 int,
+ v1 int,
+ v2 int,
+ PRIMARY KEY (k, c1, c2)
+ );
+
+then the following view definitions are allowed::
+
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (c1, k, c2);
+
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE v1 IS NOT NULL AND k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (v1, k, c1, c2);
+
+but the following ones are **not** allowed::
+
+ // Error: cannot include both v1 and v2 in the primary key as both are not in the base table primary key
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE k IS NOT NULL AND c1 IS NOT NULL AND c2 IS NOT NULL AND v1 IS NOT NULL
+ PRIMARY KEY (v1, v2, k, c1, c2)
+
+ // Error: must include k in the primary as it's a base table primary key column
+ CREATE MATERIALIZED VIEW mv1 AS
+ SELECT * FROM t WHERE c1 IS NOT NULL AND c2 IS NOT NULL
+ PRIMARY KEY (c1, c2)
+
+
+.. _mv-options:
+
+MV Options
+..........
+
+A materialized view is internally implemented by a table, and as such, creating a MV allows the :ref:`same options than
+creating a table <create-table-options>`.
+
+
+.. _alter-materialized-view-statement:
+
+ALTER MATERIALIZED VIEW
+.......................
+
+After creation, you can alter the options of a materialized view using the ``ALTER MATERIALIZED VIEW`` statement:
+
+.. code-block::
+
+ alter_materialized_view_statement: ALTER MATERIALIZED VIEW `view_name` WITH `table_options`
+
+The options that can be updated with an ALTER statement are the same as those used with a CREATE statement (see :ref:`Create table options <create-table-options>`).
+
+.. _drop-materialized-view-statement:
+
+DROP MATERIALIZED VIEW
+......................
+
+Dropping a materialized view users the ``DROP MATERIALIZED VIEW`` statement:
+
+.. code-block::
+
+ drop_materialized_view_statement: DROP MATERIALIZED VIEW [ IF EXISTS ] `view_name`;
+
+If the materialized view does not exist, the statement will return an error unless ``IF EXISTS`` is used, in which case
+the operation is a no-op.
+
+
+:doc:`Apache Cassandra Query Language </getting-started/cql/>`
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/non-reserved-keywords.rst b/docs/getting-started/non-reserved-keywords.rst
--- a/docs/getting-started/non-reserved-keywords.rst
+++ b/docs/getting-started/non-reserved-keywords.rst
@@ -0,0 +1,77 @@
+Non-Reserved CQL Keywords
+=========================
+
+CQL distinguishes between reserved and non-reserved keywords.
+
+Non-reserved keywords only have meaning in their particular area of context and can be used as an identifier. The following keywords are non-reserved:
+
+* AGGREGATE
+* ALL
+* AS
+* ASCII
+* BIGINT
+* BLOB
+* BOOLEAN
+* CALLED
+* CLUSTERING
+* COMPACT
+* CONTAINS
+* COUNT
+* COUNTER
+* CUSTOM
+* DATE
+* DECIMAL
+* DISTINCT
+* DOUBLE
+* EXISTS
+* FILTERING
+* FINALFUNC
+* FLOAT
+* FROZEN
+* FUNCTION
+* FUNCTIONS
+* INET
+* INITCOND
+* INPUT
+* INT
+* JSON
+* KEY
+* KEYS
+* KEYSPACES
+* LANGUAGE
+* LIST
+* LOGIN
+* MAP
+* NOLOGIN
+* NOSUPERUSER
+* OPTIONS
+* PASSWORD
+* PERMISSION
+* PERMISSIONS
+* RETURNS
+* ROLE
+* ROLES
+* SFUNC
+* SMALLINT
+* STATIC
+* STORAGE
+* STYPE
+* SUPERUSER
+* TEXT
+* TIME
+* TIMESTAMP
+* TIMEUUID
+* TINYINT
+* TRIGGER
+* TTL
+* TUPLE
+* TYPE
+* USER
+* USERS
+* UUID
+* VALUES
+* VARCHAR
+* VARINT
+* WRITETIME
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/os-support.rst b/docs/getting-started/os-support.rst
--- a/docs/getting-started/os-support.rst
+++ b/docs/getting-started/os-support.rst
@@ -0,0 +1,81 @@
+OS Support by Platform and Version
+==================================
+
+The following matrix shows which Operating Systems, Platforms, and Containers / Instance Engines are supported with which versions of Scylla.
+
+Scylla requires a fix to the XFS append introduced in kernel 3.15 (back-ported to 3.10 in RHEL/CentOS).
+Scylla will not run with earlier kernel versions. Details in `Scylla issue 885 <https://github.com/scylladb/scylla/issues/885>`_.
+
+.. note::
+
+ Scylla Open Source supports x86_64 for all versions and aarch64 starting from Scylla 4.6 and nightly build. In particular, aarch64 support includes AWS EC2 Graviton.
+
+ For Scylla Open Source **4.5** and later, the recommended OS and Scylla AMI/IMage OS is Ubuntu 20.04.4 LTS.
+
+
+Scylla Open Source
+-------------------
+
+.. note:: For Enterprise versions **prior to** 4.6, the recommended OS and Scylla AMI/Image OS is CentOS 7.
+
+ For Scylla Open Source versions **4.6 and later**, the recommended OS and Scylla AMI/Image OS is Ubuntu 20.04.
+
+
+
++--------------------------+----------------------------------+-----------------------------+-------------+
+| Platform | Ubuntu | Debian | Centos/RHEL |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| Scylla Version / Version | 14.04| 16.04| 18.04|20.04 |22.04 | 8 | 9 | 10 | 11 | 7 | 8 |
++==========================+======+======+======+======+======+======+======+=======+=======+======+======+
+| 5.0 | |x| | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.6 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.5 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.4 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.3 | |x| | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.2 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.1 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |v| | |x| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 4.0 | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 3.x | |x| | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 2.3 | |v| | |v| | |v| | |x| | |x| | |v| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+| 2.2 | |v| | |v| | |x| | |x| | |x| | |v| | |x| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+-------+-------+------+------+
+
+
+All releases are available as a Docker container, EC2 AMI, and a GCP image (GCP image from version 4.3).
+
+
+Scylla Enterprise
+-----------------
+
+.. note:: Enterprise versions **prior to** 2021.1, the recommended OS and Scylla AMI/IMage OS is CentOS 7.
+
+ For Enterprise versions **2021.1 and later**, the recommended OS and Scylla AMI/IMage OS is Ubuntu 20.04.4 LTS.
+
+ For Enterprise versions **2021.1 and later**, the recommended OS and Scylla AMI/Image OS is Ubuntu 20.04.
+
++--------------------------+---------------------------+--------------------+------------+
+| Platform | Ubuntu | Debian | Centos/RHEL|
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| Scylla Version / Version | 14 | 16 | 18 | 20 | 8 | 9 | 10 | 7 | 8 |
++==========================+======+======+======+======+======+======+======+======+=====+
+| 2021.1 | |x| | |v| | |v| | |v| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2020.1 | |x| | |v| | |v| | |x| | |x| | |v| | |v| | |v| | |v| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2019.1 | |x| | |v| | |v| | |x| | |x| | |v| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+| 2018.1 | |v| | |v| | |x| | |x| | |v| | |x| | |x| | |v| | |x| |
++--------------------------+------+------+------+------+------+------+------+------+-----+
+
+
+All releases are available as a Docker container, EC2 AMI, and a GCP image (GCP image from version 2021.1).
diff --git a/docs/getting-started/requirements.rst b/docs/getting-started/requirements.rst
--- a/docs/getting-started/requirements.rst
+++ b/docs/getting-started/requirements.rst
@@ -0,0 +1,34 @@
+
+===================
+Scylla Requirements
+===================
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ system-requirements
+ os-support
+ scylla-in-a-shared-environment
+
+
+.. raw:: html
+
+
+ <div class="panel callout radius animated">
+ <div class="row">
+ <div class="medium-3 columns">
+ <h5 id="getting-started">Scylla Requirements</h5>
+ </div>
+ <div class="medium-9 columns">
+
+* :doc:`Scylla System Requirements Guide</getting-started/system-requirements/>`
+* :doc:`OS Support by Platform and Version</getting-started/os-support/>`
+* :doc:`Running Scylla in a shared environment </getting-started/scylla-in-a-shared-environment>`
+
+.. raw:: html
+
+ </div>
+ </div>
+ </div>
+
diff --git a/docs/getting-started/reserved-keywords.rst b/docs/getting-started/reserved-keywords.rst
--- a/docs/getting-started/reserved-keywords.rst
+++ b/docs/getting-started/reserved-keywords.rst
@@ -0,0 +1,66 @@
+Reserved CQL Keywords
+=====================
+
+CQL distinguishes between reserved and non-reserved keywords.
+
+Reserved keywords cannot be used as identifiers. They are truly reserved for the language (but one can enclose a reserved keyword by single or double-quotes to use it as an identifier). The following keywords are reserved:
+
+
+* ADD
+* ALLOW
+* ALTER
+* AND
+* APPLY
+* ASC
+* AUTHORIZE
+* BATCH
+* BEGIN
+* BY
+* COLUMNFAMILY
+* CREATE
+* DELETE
+* DESC
+* DESCRIBE
+* DROP
+* ENTRIES
+* EXECUTE
+* FROM
+* FULL
+* GRANT
+* IF
+* IN
+* INDEX
+* INFINITY
+* INSERT
+* INTO
+* KEYSPACE
+* LIMIT
+* MODIFY
+* NAN
+* NORECURSIVE
+* NOT
+* NULL
+* OF
+* ON
+* OR
+* ORDER
+* PRIMARY
+* RENAME
+* REPLACE
+* REVOKE
+* SCHEMA
+* SELECT
+* SET
+* TABLE
+* TO
+* TOKEN
+* TRUNCATE
+* UNLOGGED
+* UPDATE
+* USE
+* USING
+* VIEW
+* WHERE
+* WITH
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/scylla-in-a-shared-environment.rst b/docs/getting-started/scylla-in-a-shared-environment.rst
--- a/docs/getting-started/scylla-in-a-shared-environment.rst
+++ b/docs/getting-started/scylla-in-a-shared-environment.rst
@@ -0,0 +1,85 @@
+
+==============================
+Scylla in a Shared Environment
+==============================
+
+Scylla is designed to utilize all of the resources on the machine. It
+runs on: disk and network bandwidth, RAM, and CPU. This allows you to
+achieve maximum performance with a minimal node count. In development
+and test, however, your nodes might be using a shared machine, which
+Scylla cannot dominate. This article explains how to configure Scylla
+for shared environments. For some production environments, these settings
+may be preferred as well.
+
+Note that a Docker image is a viable and even simpler option - `Scylla
+on dockerhub <https://hub.docker.com/r/scylladb/scylla/>`_
+
+
+Memory
+------
+
+The most critical resource that Scylla consumes is memory. By default,
+when Scylla starts up, it inspects the node's hardware configuration and
+claims *all* memory to itself, leaving some reserve for the operating
+system (OS). This is in contrast to most open-source databases that
+leave most memory for the OS, but is similar to most commercial
+databases.
+
+In a shared environment, particularly on a desktop or laptop, gobbling
+up all the machine's memory can reduce the user experience, so Scylla
+allows reducing its memory usage to a given quantity.
+
+On Ubuntu, open a terminal and edit ``/etc/default/scylla-server``, and add ``--memory 2G``
+to restrict Scylla to 2 gigabytes of RAM.
+
+On Red Hat / CentOS, open a terminal and edit ``/etc/sysconfig/scylla-server``, and add
+``--memory 2G`` to restrict Scylla to 2 gigabytes of RAM.
+
+If starting Scylla from the command line, simply append ``--memory 2G``
+to your command line.
+
+CPU
+---
+
+By default, Scylla will utilize *all* of your processors (in some
+configurations, particularly on Amazon AWS, it may leave a core for the
+operating system). In addition, Scylla will pin its threads to specific
+cores in order to maximize the utilization of the processor on-chip
+caches. On a dedicated node, this allows maximum throughput, but on a
+desktop or laptop, it can cause a sluggish user interface.
+
+Scylla offers two options to restrict its CPU utilization:
+
+- ``--smp N`` restricts Scylla to N logical cores; for example with
+ ``--smp 2`` Scylla will not utilize more than two logical cores
+- ``--overprovisioned`` tells Scylla that the machine it is running on
+ is used by other processes; so Scylla will not pin its threads or
+ memory, and will reduce the amount of polling it does to a minimum.
+
+On Ubuntu edit ``/etc/default/scylla-server``, and add
+``--smp 2 --overprovisioned`` to restrict Scylla to 2 logical cores.
+
+On Red Hat / CentOS edit ``/etc/sysconfig/scylla-server``, and add
+``--smp 2 --overprovisioned`` to restrict Scylla to 2 logical cores.
+
+If starting Scylla from the command line, simply append
+``--smp 2 --overprovisioned`` to your command line.
+
+Other Restrictions
+------------------
+
+When starting up, Scylla will check the hardware and operating system
+configuration to verify that it is compatible with Scylla's performance requirements. See `developer mode`_ for more instructions.
+
+.. _`developer mode`: /getting-started/install-scylla/dev_mod/
+
+
+Summary
+-------
+
+Scylla comes out of the box ready for production use with maximum
+performance but may need to be tuned for development or test uses. This
+tuning is simple to apply and results in a Scylla server that can
+coexist with other processes or a GUI on the system.
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/secondary-indexes.rst b/docs/getting-started/secondary-indexes.rst
--- a/docs/getting-started/secondary-indexes.rst
+++ b/docs/getting-started/secondary-indexes.rst
@@ -0,0 +1,122 @@
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _secondary-indexes:
+
+Global Secondary Indexes
+------------------------
+
+Global Secondary Indexes is production ready in Scylla Open Source 3.0 and Scylla Enterprise 2019.1.x
+
+
+CQL supports creating secondary indexes on tables, allowing queries on the table to use those indexes. A secondary index
+is identified by a name defined by:
+
+.. code-block::
+
+ index_name: re('[a-zA-Z_0-9]+')
+
+
+
+.. _create-index-statement:
+
+CREATE INDEX
+^^^^^^^^^^^^
+
+Creating a secondary index on a table uses the ``CREATE INDEX`` statement:
+
+.. code-block::
+
+ create_index_statement: CREATE INDEX [ `index_name` ]
+ : ON `table_name` '(' `index_identifier` ')'
+ : [ USING `string` [ WITH OPTIONS = `map_literal` ] ]
+ index_identifier: `column_name`
+ :| ( FULL ) '(' `column_name` ')'
+
+For instance::
+
+ CREATE INDEX userIndex ON NerdMovies (user);
+ CREATE INDEX ON Mutants (abilityId);
+
+The ``CREATE INDEX`` statement is used to create a new (automatic) secondary index for a given (existing) column in a
+given table. A name for the index itself can be specified before the ``ON`` keyword, if desired. If data already exists
+for the column, it will be indexed asynchronously. After the index is created, new data for the column is indexed
+automatically at insertion time.
+
+Local Secondary Index
+^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: Scylla 3.1
+
+:doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes>` is an enhancement of :doc:`Global Secondary Indexes </using-scylla/secondary-indexes>`, which allows Scylla to optimize the use case in which the partition key of the base table is also the partition key of the index. Local Secondary Index syntax is the same as above, with extra parentheses on the partition key.
+
+.. code-block::
+
+ index_identifier: `column_name`
+ :| ( PK ) | KEYS | VALUES | FULL ) '(' `column_name` ')'
+
+Example:
+
+.. code-block:: cql
+
+ CREATE TABLE menus (location text, name text, price float, dish_type text, PRIMARY KEY(location, name));
+ CREATE INDEX ON menus((location),dish_type);
+
+More on :doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes>`
+
+.. Attempting to create an already existing index will return an error unless the ``IF NOT EXISTS`` option is used. If it
+.. is used, the statement will be a no-op if the index already exists.
+
+.. Indexes on Map Keys (supported in Scylla 2.2)
+.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. When creating an index on a :ref:`maps <maps>`, you may index either the keys or the values. If the column identifier is
+.. placed within the ``keys()`` function, the index will be on the map keys, allowing you to use ``CONTAINS KEY`` in
+.. ``WHERE`` clauses. Otherwise, the index will be on the map values.
+
+.. _drop-index-statement:
+
+DROP INDEX
+^^^^^^^^^^
+
+Dropping a secondary index uses the ``DROP INDEX`` statement:
+
+.. code-block::
+
+ drop_index_statement: DROP INDEX [ IF EXISTS ] `index_name`
+
+The ``DROP INDEX`` statement is used to drop an existing secondary index. The argument of the statement is the index
+name, which may optionally specify the keyspace of the index.
+
+.. If the index does not exists, the statement will return an error, unless ``IF EXISTS`` is used in which case the
+.. operation is a no-op.
+
+Additional Information
+----------------------
+
+* :doc:`Global Secondary Indexes </using-scylla/secondary-indexes/>`
+* :doc:`Local Secondary Indexes </using-scylla/local-secondary-indexes/>`
+
+The following courses are available from Scylla University:
+
+* `Materialized Views and Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/>`_
+* `Global Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/topic/global-secondary-indexes/>`_
+* `Local Secondary Indexes <https://university.scylladb.com/courses/data-modeling/lessons/materialized-views-secondary-indexes-and-filtering/topic/local-secondary-indexes-and-combining-both-types-of-indexes/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/getting-started/system-configuration.rst b/docs/getting-started/system-configuration.rst
--- a/docs/getting-started/system-configuration.rst
+++ b/docs/getting-started/system-configuration.rst
@@ -0,0 +1,3 @@
+
+
+.. include:: /getting-started/_common/system-configuration-index.rst
diff --git a/docs/getting-started/system-requirements.rst b/docs/getting-started/system-requirements.rst
--- a/docs/getting-started/system-requirements.rst
+++ b/docs/getting-started/system-requirements.rst
@@ -0,0 +1,384 @@
+===================
+System Requirements
+===================
+
+.. _system-requirements-supported-platforms:
+
+Supported Platforms
+===================
+
+Scylla runs on 64-bit Linux. Here, you can find which :doc:`operating systems, distros, and versions </getting-started/os-support>` are supported.
+
+.. _system-requirements-hardware:
+
+Hardware Requirements
+=====================
+
+It’s recommended to have a balanced setup. If there are only 4-8 :term:`Logical Cores <Logical Core (lcore)>`, large disks or 10Gbps networking may not be needed.
+This works in the opposite direction as well.
+Scylla can be used in many types of installation environments.
+
+To see which system would best suit your workload requirements, use the `Scylla Sizing Calculator <https://price-calc.gh.scylladb.com/>`_ to customize Scylla for your usage.
+
+
+
+Core Requirements
+-----------------
+Scylla tries to maximize the resource usage of all system components. The shard-per-core approach allows linear scale-up with the number of cores. As you have more cores, it makes sense to balance the other resources, from memory to network.
+
+CPU
+^^^
+Scylla requires modern Intel CPUs that support the SSE4.2 instruction set and will not boot without it.
+
+The following CPUs are supported by Scylla:
+
+* Intel core: Westmere or later (2010)
+* Intel atom: Goldmont or later (2016)
+* AMD low power: Jaguar or later (2013)
+* AMD standard: Bulldozer or later (2011)
+
+
+In terms of the number of cores, any number will work since Scylla scales up with the number of cores.
+A practical approach is to use a large number of cores as long as the hardware price remains reasonable.
+Between 20-60 logical cores (including hyperthreading) is a recommended number. However, any number will fit.
+When using virtual machines, containers, or the public cloud, remember that each virtual CPU is mapped to a single logical core, or thread.
+Allow Scylla to run independently without any additional CPU intensive tasks on the same server/cores as Scylla.
+
+.. _system-requirements-memory:
+
+Memory Requirements
+-------------------
+The more memory available, the better Scylla performs, as Scylla uses all of the available memory for caching. The wider the rows are in the schema, the more memory will be required. 64 GB-256 GB is the recommended range for a medium to high workload. Memory requirements are calculated based on the number of :abbr:`lcores (logical cores)` you are using in your system.
+
+* Recommended size: 16 GB or 2GB per lcore (whichever is higher)
+* Maximum: 1 TiB per lcore, up to 256 lcores
+* Minimum:
+
+ - For test environments: 1 GB or 256 MiB per lcore (whichever is higher)
+ - For production environments: 4 GB or 0.5 GB per lcore (whichever is higher)
+
+.. _system-requirements-disk:
+
+Disk Requirements
+-----------------
+
+SSD
+^^^
+We highly recommend SSD and local disks. Scylla is built for a large volume of data and large storage per node.
+You can use up to 100:1 Disk/RAM ratio, with 30:1 Disk/RAM ratio as a good rule of thumb; for example, 30 TB of storage requires 1 TB of RAM.
+We recommend a RAID-0 setup and a replication factor of 3 within the local datacenter (RF=3) when there are multiple drives.
+
+HDD
+^^^
+HDDs are supported but may become a bottleneck. Some workloads may work with HDDs, especially if they play nice and minimize random seeks. An example of an HDD-friendly workload is a write-mostly (98% writes) workload, with minimal random reads. If you use HDDs, try to allocate a separate disk for the commit log (not needed with SSDs).
+
+Disk Space
+^^^^^^^^^^
+Scylla is flushing memtables to SSTable data files for persistent storage. SSTables are periodically compacted to improve performance by merging and rewriting data and discarding the old one. Depending on compaction strategy, disk space utilization temporarily increases during compaction. For this reason, you should leave an adequate amount of free disk space available on a node.
+Use the following table as a guidelines for the minimum disk space requirements based on the compaction strategy:
+
+====================================== =========== ============
+Compaction Strategy Recommended Minimum
+====================================== =========== ============
+Size Tiered Compaction Strategy (STCS) 50% 70%
+-------------------------------------- ----------- ------------
+Leveled Compaction Strategy (LCS) 50% 80%
+-------------------------------------- ----------- ------------
+Time-window Compaction Strategy (TWCS) 50% 70%
+-------------------------------------- ----------- ------------
+Incremental Compaction Strategy (ICS) 70% 80%
+====================================== =========== ============
+
+Use the default ICS (Scylla Enterprise) or STCS (Scylla Open Source) unless you'll have a clear understanding that another strategy is better for your use case. More on :doc:`choosing a Compaction Strategy </architecture/compaction/compaction-strategies>`.
+In order to maintain a high level of service availability, keep 50% to 20% free disk space at all times!
+
+.. _system-requirements-network:
+
+Network Requirements
+====================
+
+A network speed of 10 Gbps or more is recommended, especially for large nodes. To tune the interrupts and their queues, run the Scylla setup scripts.
+
+
+Cloud Instance Recommendations
+===============================
+
+Amazon Web Services (AWS)
+--------------------------------
+
+.. note::
+
+ Some of the ScyllaDB configuration features rely on querying instance metadata.
+ Disabling access to instance metadata will impact using Ec2 Snitches and tuning performance.
+ See `AWS - Configure the instance metadata options <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html>`_ for more information.
+
+
+We highly recommend EC2 **I3** instances—High I/O. This family includes the High Storage Instances that provide very fast SSD-backed instance storage optimized for very high random I/O performance and provide high IOPS at a low cost. We recommend using enhanced networking that exposes the physical network cards to the VM.
+
+i3 instances are designed for I/O intensive workloads and equipped with super-efficient NVMe SSD storage. It can deliver up to 3.3 Million IOPS.
+An i3 instance is great for low latency and high throughput, compared to the i2 instances, the i3 instance provides storage that it's less expensive and denser along with the ability to deliver substantially more IOPS and more network bandwidth per CPU core.
+
+i3 instances
+^^^^^^^^^^^^
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i3.xlarge 4 30.5 0.950 TB
+--------------------------- ----------- ------------ ---------------------
+i3.2xlarge 8 61 1.9 TB
+--------------------------- ----------- ------------ ---------------------
+i3.4xlarge 16 122 3.8 TB
+--------------------------- ----------- ------------ ---------------------
+i3.8xlarge 32 244 7.6 TB
+--------------------------- ----------- ------------ ---------------------
+i3.16xlarge 64 488 15.2 TB
+--------------------------- ----------- ------------ ---------------------
+i3.metal New in version 2.3 72 :sup:`*` 512 8 x 1.9 NVMe SSD
+=========================== =========== ============ =====================
+
+:sup:`*` i3.metal provides 72 logical processors on 36 physical cores
+
+Source: `Amazon EC2 I3 Instances <https://aws.amazon.com/ec2/instance-types/i3/>`_
+
+More on using Scylla with `i3.metal vs i3.16xlarge <https://www.scylladb.com/2018/06/21/impact-virtualization-database/>`_
+
+i3en instances
+^^^^^^^^^^^^^^
+i3en instances have up to 4x the networking bandwidth of i3 instances, enabling up to 100 Gbps of sustained network bandwidth.
+
+i3en support is available for Scylla Enterprise 2019.1.1 and higher and Scylla Open Source 3.1 and higher.
+
+
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i3en.large 2 16 1 x 1,250 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.xlarge 4 32 1 x 2,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.2xlarge 8 64 2 x 2,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.3xlarge 12 96 1 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.6xlarge 24 192 2 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.12xlarge 48 384 4 x 7,500 GB
+--------------------------- ----------- ------------ ---------------------
+i3en.24xlarge 96 768 8 x 7,500 GB
+=========================== =========== ============ =====================
+
+All i3en instances have the following specs:
+
+* 3.1 GHz all-core turbo Intel® Xeon® Scalable (Skylake) processors
+* Intel AVX†, Intel AVX2†, Intel AVX-512†, Intel Turbo
+* EBS Optimized
+* Enhanced Networking
+
+See `Amazon EC2 I3en Instances <https://aws.amazon.com/ec2/instance-types/i3en/>`_ for details.
+
+
+i4i instances
+^^^^^^^^^^^^^^
+i4i support is available for ScyllaDB Open Source 5.0 and later and ScyllaDB Enterprise 2021.1.10 and later.
+
+
+
+=========================== =========== ============ =====================
+Model vCPU Mem (GB) Storage (NVMe SSD)
+=========================== =========== ============ =====================
+i4i.large 2 16 1 x 468 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.xlarge 4 32 1 x 937 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.2xlarge 8 64 1 x 1,875 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.4xlarge 16 128 1 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.8xlarge 32 256 2 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.16xlarge 64 512 4 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.32xlarge 128 1,024 8 x 3,750 GB
+--------------------------- ----------- ------------ ---------------------
+i4i.metal 128 1,024 8 x 3,750 GB
+=========================== =========== ============ =====================
+
+All i41 instances have the following specs:
+
+* 3.5 GHz all-core turbo Intel® Xeon® Scalable (Ice Lake) processors
+* 40 Gbps bandwidth to EBS in the largest size and up to 10 Gbps in the four smallest sizes (twice that of i3 instances. Up to 75 Gbps networking bandwidth (three times more than I3 instances).
+* AWS Nitro SSD storage
+
+
+See `Amazon EC2 I4i Instances <https://aws.amazon.com/ec2/instance-types/i4i/>`_ for specification details.
+
+See `ScyllaDB on the New AWS EC2 I4i Instances: Twice the Throughput & Lower Latency <https://www.scylladb.com/2022/05/09/scylladb-on-the-new-aws-ec2-i4i-instances-twice-the-throughput-lower-latency/>`_ to
+learn more about using ScyllaDB with i4i instances.
+
+
+Google Compute Engine (GCE)
+-----------------------------------
+
+Pick a zone where Haswell CPUs are found. Local SSD performance offers, according to Google, less than 1 ms of latency and up to 680,000 read IOPS and 360,000 write IOPS.
+Image with NVMe disk interface is recommended, CentOS 7 for Scylla Enterprise 2020.1 and older, and Ubuntu 20 for 2021.1 and later.
+(`More info <https://cloud.google.com/compute/docs/disks/local-ssd>`_)
+
+Recommended instances types are `n1-highmem <https://cloud.google.com/compute/docs/general-purpose-machines#n1_machines>`_ and `n2-highmem <https://cloud.google.com/compute/docs/general-purpose-machines#n2_machines>`_
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage (GB)
+ * - n1-highmem-2
+ - 2
+ - 13
+ - 375
+ * - n1-highmem-4
+ - 4
+ - 26
+ - 750
+ * - n1-highmem-8
+ - 8
+ - 52
+ - 1,500
+ * - n1-highmem-16
+ - 16
+ - 104
+ - 3,000
+ * - n1-highmem-32
+ - 32
+ - 208
+ - 6,000
+ * - n1-highmem-64
+ - 64
+ - 416
+ - 9,000
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage (GB)
+ * - n2-highmem-2
+ - 2
+ - 16
+ - 375
+ * - n2-highmem-4
+ - 4
+ - 32
+ - 750
+ * - n2-highmem-8
+ - 8
+ - 64
+ - 1500
+ * - n2-highmem-16
+ - 16
+ - 128
+ - 3,000
+ * - n2-highmem-32
+ - 32
+ - 256
+ - 6,000
+ * - n2-highmem-48
+ - 48
+ - 384
+ - 9,000
+ * - n2-highmem-64
+ - 64
+ - 512
+ - 9,000
+ * - n2-highmem-80
+ - 80
+ - 640
+ - 9,000
+
+
+Storage: each instance can support maximum of 24 local SSD of 375 GB partitions each for a total of `9 TB per instance <https://cloud.google.com/compute/docs/disks>`_
+
+.. _system-requirements-azure:
+
+Microsoft Azure
+---------------
+
+The `Lsv2-series <https://azure.microsoft.com/en-us/blog/announcing-the-general-availability-of-lsv2-series-azure-virtual-machines/>`_ features high throughput, low latency, and directly mapped local NVMe storage. The Lsv2 VMs run on the AMD EPYCTM 7551 processor with an all-core boost of 2.55GHz.
+
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - vCPU
+ - Mem (GB)
+ - Storage
+ * - L8s_v2
+ - 8
+ - 64
+ - 1 x 1.92 TB
+ * - L16s_v2
+ - 16
+ - 128
+ - 2 x 1.92 TB
+ * - L32s_v2
+ - 32
+ - 256
+ - 4 x 1.92 TB
+ * - L48s_v2
+ - 48
+ - 384
+ - 6 x 1.92 TB
+ * - L64s_v2
+ - 64
+ - 512
+ - 8 x 1.92 TB
+ * - L80s_v2
+ - 80
+ - 640
+ - 10 x 1.92 TB
+
+More on Azure Lsv2 instances `here <https://azure.microsoft.com/en-us/blog/announcing-the-general-availability-of-lsv2-series-azure-virtual-machines/>`_
+
+Oracle Cloud Infrastructure (OCI)
+----------------------------------------
+
+An OCPU is defined as the CPU capacity equivalent of one physical core of an Intel Xeon processor with hyperthreading enabled.
+For Intel Xeon processors, each OCPU corresponds to two hardware execution threads, known as vCPUs.
+
+
+.. list-table::
+ :widths: 30 20 20 30
+ :header-rows: 1
+
+ * - Model
+ - OCPU
+ - Mem (GB)
+ - Storage
+ * - VM.DenseIO2.8
+ - 8
+ - 120
+ - 6.4 TB
+ * - VM.DenseIO2.16
+ - 16
+ - 240
+ - 12.8 TB
+ * - VM.DenseIO2.24
+ - 24
+ - 320
+ - 25.6 TB
+ * - BM.DenseIO2.52
+ - 52
+ - 768
+ - 51.2 TB
+ * - BM.HPC2.36
+ - 36
+ - 384
+ - 6.7 TB
+
+.. include:: /rst_include/advance-index.rst
diff --git a/docs/getting-started/time-to-live.rst b/docs/getting-started/time-to-live.rst
--- a/docs/getting-started/time-to-live.rst
+++ b/docs/getting-started/time-to-live.rst
@@ -0,0 +1,108 @@
+
+
+.. highlight:: cql
+
+.. _time-to-live:
+
+Expiring Data with Time to Live (TTL)
+-------------------------------------
+
+Scylla (as well as Apache Cassandra) provides the functionality to automatically delete expired data according to the Time to Live (or TTL) value.
+TTL is measured in seconds. If the field is not updated within the TTL it is deleted.
+The TTL can be set when defining a Table (CREATE), or when using the INSERT and UPDATE queries.
+The expiration works at the individual column level, which provides a lot of flexibility.
+By default, the TTL value is null, which means that the data will not expire.
+
+.. note::
+
+ The expiration time is always calculated as *now() on the Coordinator + TTL* where, *now()* is the wall clock during the corresponding write operation.
+ In particular, it means that a value given via USING TIMESTAMP is **not** taken into an account for an expiration calculation.
+
+TTL using UPDATE and INSERT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To set the TTL value using the UPDATE query use the following command:
+
+.. code-block:: cql
+
+ UPDATE heartrate USING TTL 600 SET heart_rate =
+ 110 WHERE pet_chip_id = 123e4567-e89b-12d3-a456-426655440b23;
+
+In this case, the TTL for the heart_rate column is set 10 minutes (600 seconds).
+
+To check the TTL, use the ``TTL()`` function:
+
+.. code-block:: cql
+
+ SELECT name, heart_rate, TTL(heart_rate)
+ FROM heartrate WHERE pet_chip_id = 123e4567-e89b-12d3-a456-426655440b23;
+
+The TTL has a value that is lower than 600 as a few seconds passed between setting the TTL and the SELECT query.
+If you wait 10 minutes and run this command again, you will get a null value for the heart_rate.
+
+It’s also possible to set the TTL when performing an INSERT. To do this use:
+
+.. code-block:: cql
+
+ INSERT INTO heartrate(pet_chip_id, name, heart_rate) VALUES (c63e71f0-936e-11ea-bb37-0242ac130002, 'Rocky', 87) USING TTL 30;
+
+In this case, a TTL of 30 seconds is set.
+
+
+TTL for a Table
+^^^^^^^^^^^^^^^
+Use the CREATE TABLE or ALTER TABLE commands and set the default_time_to_live value:
+
+.. code-block:: cql
+
+ CREATE TABLE heartrate_ttl (
+ pet_chip_id uuid,
+ name text,
+ heart_rate int,
+ PRIMARY KEY (pet_chip_id))
+ WITH default_time_to_live = 600;
+
+Here a TTL of 10 minutes is applied to all rows, however, keep in mind that TTL is stored on a per column level for non-primary key columns.
+
+It’s also possible to change the default_time_to_live on an existing table using the ALTER command:
+
+.. code-block:: cql
+
+ ALTER TABLE heartrate_ttl WITH default_time_to_live = 3600;
+
+TTL with LWT
+.............
+
+.. include:: /rst_include/note-ttl-lwt.rst
+
+Refer to :doc:`LWT </using-scylla/lwt/>` for more information.
+
+The ``gc_grace_seconds`` parameter is defined :ref:`here <create-table-general-options>`.
+
+
+
+TTL for a Collection
+^^^^^^^^^^^^^^^^^^^^
+
+You can set the TTL on a per element basis for collections. An example of how to do this, is shown in the :ref:`Maps <maps>` CQL Reference.
+
+Notes
+^^^^^
+* Notice that setting the TTL on a column using UPDATE or INSERT overrides the default_time_to_live set at the Table level.
+* The TTL is determined by the coordinator node. When using TTL, make sure that all the nodes in the cluster have synchronized clocks.
+* When using TTL for a table, consider using the TWCS compaction strategy.
+* Scylla defines TTL on a per column basis, for non-primary key columns. It’s impossible to set the TTL for the entire row after an initial insert; instead, you can reinsert the row (which is actually an upsert).
+* TTL can not be defined for counter columns.
+* To remove the TTL, set it to 0.
+
+
+
+Additional Information
+----------------------
+
+To learn more about TTL, and see a hands-on example, check out `this lesson <https://university.scylladb.com/courses/data-modeling/lessons/advanced-data-modeling/topic/expiring-data-with-ttl-time-to-live/>`_ on Scylla University.
+
+* :doc:`Apache Cassandra Query Language </getting-started/cql/>`
+* :doc:`KB Article:How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds/>`
+* :doc:`KB Article:Time to Live (TTL) and Compaction </kb/ttl-facts/>`
+* :ref:`CQL Reference: Table Options <create-table-general-options>`
diff --git a/docs/getting-started/tutorials.rst b/docs/getting-started/tutorials.rst
--- a/docs/getting-started/tutorials.rst
+++ b/docs/getting-started/tutorials.rst
@@ -0,0 +1,16 @@
+============
+Tutorials
+============
+
+The tutorials will show you how to use ScyllaDB as a data source for an application.
+
+
+ScyllaDB Tutorial
+===================
+
+`Build an IoT App with sensor simulator and a REST API <https://care-pet.docs.scylladb.com/>`_
+
+ScyllaDB Cloud Tutorial
+=======================
+
+`Implement CRUD operations with a TODO App <https://github.com/scylladb/scylla-cloud-getting-started/>`_
diff --git a/docs/getting-started/types.rst b/docs/getting-started/types.rst
--- a/docs/getting-started/types.rst
+++ b/docs/getting-started/types.rst
@@ -0,0 +1,679 @@
+Data Types
+----------
+.. _data-types:
+
+
+.. highlight:: cql
+
+.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+
+
+
+.. include:: /rst_include/cql-version-index.rst
+
+
+
+CQL is a typed language and supports a rich set of data types, including :ref:`native types <native-types>` and
+:ref:`collection types <collections>`.
+
+.. code-block::
+
+ cql_type: `native_type` | `collection_type` | `user_defined_type` | `tuple_type`
+
+
+
+Working with Bytes
+^^^^^^^^^^^^^^^^^^
+
+Bytes can be input with:
+
+* a hexadecimal literal.
+* one of the ``typeAsBlob()`` cql functions. There is such a function for each native type.
+
+For example:
+
+.. code-block:: cql
+
+
+ INSERT INTO blobstore (id, data) VALUES (4375645, 0xabf7971528cfae76e00000008bacdf);
+ INSERT INTO blobstore (id, data) VALUES (4375645, intAsBlob(33));
+
+.. _native-types:
+
+Native Types
+^^^^^^^^^^^^
+
+The native types supported by CQL are:
+
+.. code-block:: cql
+
+ native_type: ASCII
+ : | BIGINT
+ : | BLOB
+ : | BOOLEAN
+ : | COUNTER
+ : | DATE
+ : | DECIMAL
+ : | DOUBLE
+ : | DURATION
+ : | FLOAT
+ : | INET
+ : | INT
+ : | SMALLINT
+ : | TEXT
+ : | TIME
+ : | TIMESTAMP
+ : | TIMEUUID
+ : | TINYINT
+ : | UUID
+ : | VARCHAR
+ : | VARINT
+
+The following table gives additional information on the native data types and which kind of :ref:`constants
+<constants>` each type supports:
+
+======================= ===================== ========================================================================================================
+ type constants supported description
+======================= ===================== ========================================================================================================
+ ``ascii`` :token:`string` ASCII character string
+ ``bigint`` :token:`integer` 64-bit signed long
+ ``blob`` :token:`blob` Arbitrary bytes (no validation). See `Working with Bytes`_ for details
+ ``boolean`` :token:`boolean` Either ``true`` or ``false``
+ ``counter`` :token:`integer` Counter column (64-bit signed value). See :ref:`counters` for details
+ ``date`` :token:`integer`, A date (with no corresponding time value). See :ref:`dates` below for details
+ :token:`string`
+ ``decimal`` :token:`integer`, Variable-precision decimal
+ :token:`float`
+ ``double`` :token:`integer` 64-bit IEEE-754 floating point
+ :token:`float`
+ ``duration`` :token:`duration`, A duration with nanosecond precision. See :ref:`durations` below for details
+ ``float`` :token:`integer`, 32-bit IEEE-754 floating point
+ :token:`float`
+ ``inet`` :token:`string` An IP address, either IPv4 (4 bytes long) or IPv6 (16 bytes long). Note that
+ there is no ``inet`` constant, IP address should be input as strings
+ ``int`` :token:`integer` 32-bit signed int
+ ``smallint`` :token:`integer` 16-bit signed int
+ ``text | varchar`` :token:`string` UTF8 encoded string
+ ``time`` :token:`integer`, A time (with no corresponding date value) with nanosecond precision. See
+ :token:`string` :ref:`times` below for details
+ ``timestamp`` :token:`integer`, A timestamp (date and time) with millisecond precision. See :ref:`timestamps`
+ :token:`string` below for details
+ ``timeuuid`` :token:`uuid` Version 1 UUID_, generally used as a “conflict-free” timestamp. See `Working with UUIDs`_ for details
+ ``tinyint`` :token:`integer` 8-bit signed int
+ ``uuid`` :token:`uuid` A UUID_ (of any version). See `Working with UUIDs`_ for details
+ ``varint`` :token:`integer` Arbitrary-precision integer
+======================= ===================== ========================================================================================================
+
+.. _counters:
+
+Counters
+~~~~~~~~
+
+The ``counter`` type is used to define *counter columns*. A counter column is a column with a 64-bit signed
+integer value and on which two operations are supported: incrementing and decrementing (see the :ref:`UPDATE statement
+<update-statement>` for syntax). Note that the value of a counter cannot be set: a counter does not exist until first
+incremented/decremented, and that first increment/decrement is made as if the prior value was 0.
+
+.. _counter-limitations:
+
+Counters have a number of important limitations:
+
+- They cannot be used for columns part of the ``PRIMARY KEY`` of a table.
+- A table that contains a counter can only contain counters. In other words, either all the columns of a table outside
+ the ``PRIMARY KEY`` have the ``counter`` type, or none of them have it.
+- Counters do not support expiration.
+- The deletion of counters is supported but is only guaranteed to work the first time you delete a counter. In other
+ words, you should not re-update a counter that you have deleted (if you do, proper behavior is not guaranteed).
+- Counter updates are, by nature, **not** `idempotent <https://en.wikipedia.org/wiki/Idempotence>`__. An important
+ consequence is that if a counter update fails unexpectedly (timeout or loss of connection to the coordinator node),
+ the client has no way to know if the update has been applied or not. In particular, replaying the update may or may
+ not lead to an overcount.
+
+.. _timestamps:
+
+Working with timestamps
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Values of the ``timestamp`` type are encoded as 64-bit signed integers representing a number of milliseconds since the
+standard base time known as `the epoch <https://en.wikipedia.org/wiki/Unix_time>`__: January 1st 1970 at 00:00:00 GMT.
+
+Timestamps can be input in CQL either using their value as an :token:`integer`, or using a :token:`string` that
+represents an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ date. For instance, all of the values below are
+valid ``timestamp`` values for Mar 2, 2011, at 04:05:00 AM, GMT:
+
+- ``1299038700000``
+- ``'2011-02-03 04:05+0000'``
+- ``'2011-02-03 04:05:00+0000'``
+- ``'2011-02-03 04:05:00.000+0000'``
+- ``'2011-02-03T04:05+0000'``
+- ``'2011-02-03T04:05:00+0000'``
+- ``'2011-02-03T04:05:00.000+0000'``
+
+The ``+0000`` above is an RFC 822 4-digit time zone specification; ``+0000`` refers to GMT. US Pacific Standard Time is
+``-0800``. The time zone may be omitted if desired (``'2011-02-03 04:05:00'``), and if so, the date will be interpreted
+as being in the time zone under which the coordinating Scylla node is configured. However, there are difficulties
+inherent in relying on the time zone configuration as expected, so it is recommended that the time zone always be
+specified for timestamps when feasible.
+
+The time of day may also be omitted (``'2011-02-03'`` or ``'2011-02-03+0000'``), in which case the time of day will
+default to 00:00:00 in the specified or default time zone. However, if only the date part is relevant, consider using
+the :ref:`date <dates>` type.
+
+.. _dates:
+
+Working with dates
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``date`` type are encoded as 32-bit unsigned integers representing a number of days with “the epoch” at
+the center of the range (2^31). Epoch is January 1st, 1970.
+
+As for :ref:`timestamp <timestamps>`, a date can be input either as an :token:`integer` or using a date
+:token:`string`. In the latter case, the format should be ``yyyy-mm-dd`` (so ``'2011-02-03'``, for instance).
+
+.. _times:
+
+Working with times
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``time`` type are encoded as 64-bit signed integers representing the number of nanoseconds since midnight.
+
+As for :ref:`timestamp <timestamps>`, time can be input either as an :token:`integer` or using a :token:`string`
+representing the time. In the latter case, the format should be ``hh:mm:ss[.fffffffff]`` (where the sub-second precision
+is optional and if provided, can be less than the nanosecond). So, for instance, the following are valid inputs for a
+time:
+
+- ``'08:12:54'``
+- ``'08:12:54.123'``
+- ``'08:12:54.123456'``
+- ``'08:12:54.123456789'``
+
+.. _durations:
+
+Working with durations
+^^^^^^^^^^^^^^^^^^^^^^
+
+Values of the ``duration`` type are encoded as three signed integers of variable lengths. The first integer represents the
+number of months, the second the number of days, and the third the number of nanoseconds. This is due to the fact that
+the number of days in a month can change, and a day can have 23 or 25 hours depending on the daylight saving.
+Internally, the number of months and days is decoded as 32 bits integers, whereas the number of nanoseconds is decoded
+as a 64 bits integer.
+
+A duration can be input as:
+
+#. ``(quantity unit)+`` like ``12h30m`` where the unit can be:
+
+ * ``y``: years (12 months)
+ * ``mo``: months (1 month)
+ * ``w``: weeks (7 days)
+ * ``d``: days (1 day)
+ * ``h``: hours (3,600,000,000,000 nanoseconds)
+ * ``m``: minutes (60,000,000,000 nanoseconds)
+ * ``s``: seconds (1,000,000,000 nanoseconds)
+ * ``ms``: milliseconds (1,000,000 nanoseconds)
+ * ``us`` or ``µs`` : microseconds (1000 nanoseconds)
+ * ``ns``: nanoseconds (1 nanosecond)
+#. ISO 8601 format: ``P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W``
+#. ISO 8601 alternative format: ``P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]``
+
+For example::
+
+ INSERT INTO RiderResults (rider, race, result) VALUES ('Christopher Froome', 'Tour de France', 89h4m48s);
+ INSERT INTO RiderResults (rider, race, result) VALUES ('BARDET Romain', 'Tour de France', PT89H8M53S);
+ INSERT INTO RiderResults (rider, race, result) VALUES ('QUINTANA Nairo', 'Tour de France', P0000-00-00T89:09:09);
+
+.. _duration-limitation:
+
+Duration columns cannot be used in a table's ``PRIMARY KEY``. This limitation is due to the fact that
+durations cannot be ordered. It is effectively not possible to know if ``1mo`` is greater than ``29d`` without a date
+context.
+
+A ``1d`` duration does not equal to a ``24h`` one as the duration type has been created to be able to support daylight
+saving.
+
+Working with UUIDs
+^^^^^^^^^^^^^^^^^^
+
+The values of the UUID type are encoded as 32 hex (base 16) digits,
+in five groups separated by hyphens (-), in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens).
+
+Use an integer literal and not a string. For example ``123e4567-e89b-12d3-a456-426655440000`` and not ``'123e4567-e89b-12d3-a456-426655440000'``.
+
+
+.. _collections:
+
+Collections
+^^^^^^^^^^^
+
+CQL supports 3 kinds of collections: :ref:`maps`, :ref:`sets` and :ref:`lists`. The types of those collections is defined
+by:
+
+.. code-block:: cql
+
+ collection_type: MAP '<' `cql_type` ',' `cql_type` '>'
+ : | SET '<' `cql_type` '>'
+ : | LIST '<' `cql_type` '>'
+
+and their values can be input using collection literals:
+
+.. code-block:: cql
+
+ collection_literal: `map_literal` | `set_literal` | `list_literal`
+
+ map_literal: '{' [ `term` ':' `term` (',' `term` : `term`)* ] '}'
+
+ set_literal: '{' [ `term` (',' `term`)* ] '}'
+
+ list_literal: '[' [ `term` (',' `term`)* ] ']'
+
+Note that neither :token:`bind_marker` nor ``NULL`` are supported inside collection literals.
+
+Noteworthy characteristics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Collections are meant for storing/denormalizing a relatively small amount of data. They work well for things like “the
+phone numbers of a given user”, “labels applied to an email”, etc. But when items are expected to grow unbounded (“all
+messages sent by a user”, “events registered by a sensor”...), then collections are not appropriate, and a specific table
+(with clustering columns) should be used. A collection can be **frozen** or **non-frozen**.
+A non-frozen collection can be modified, i.e., have an element added or removed. A
+frozen collection can only be updated as a whole. By default, a collection is non-frozen.
+To declare a frozen collection, use ``FROZEN`` keyword:
+
+.. code-block:: cql
+
+ frozen_collection_type: FROZEN '<' MAP '<' `cql_type` ',' `cql_type` '>' '>'
+ : | FROZEN '<' SET '<' `cql_type` '>' '>'
+ : | FROZEN '<' LIST '<' `cql_type` '>' '>'
+
+Non-frozen collections have the following noteworthy characteristics and limitations:
+
+- Individual collections are not indexed internally. This means that even to access a single element of a collection,
+ the whole collection has to be read (and reading one is not paged internally).
+- While insertion operations on sets and maps never incur a read-before-write internally, some operations on lists do.
+ Further, some list operations are not idempotent by nature (see the section on :ref:`lists <lists>` below for
+ details), making their retry in case of timeout problematic. It is thus advised to prefer sets over lists when
+ possible.
+
+Please note that while some of those limitations may or may not be removed/improved upon in the future, it is an
+anti-pattern to use a (single) collection to store large amounts of data.
+
+.. _maps:
+
+Maps
+~~~~
+
+A ``map`` is a (sorted) set of key-value pairs, where keys are unique, and the map is sorted by its keys. You can define a map column with::
+
+ CREATE TABLE users (
+ id text PRIMARY KEY,
+ name text,
+ favs map<text, text> // A map of text keys, and text values
+ );
+
+A map column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the map's
+old content, if any::
+
+ INSERT INTO users (id, name, favs)
+ VALUES ('jsmith', 'John Smith', { 'fruit' : 'Apple', 'band' : 'Beatles' });
+
+ UPDATE users SET favs = { 'fruit' : 'Banana' } WHERE id = 'jsmith';
+
+Note that Scylla does not distinguish an empty map from a missing value,
+thus assigning an empty map (``{}``) to a map is the same as deleting it.
+
+Further, maps support:
+
+- Updating or inserting one or more elements::
+
+ UPDATE users SET favs['author'] = 'Ed Poe' WHERE id = 'jsmith';
+ UPDATE users SET favs = favs + { 'movie' : 'Cassablanca', 'band' : 'ZZ Top' } WHERE id = 'jsmith';
+
+- Removing one or more element (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ DELETE favs['author'] FROM users WHERE id = 'jsmith';
+ UPDATE users SET favs = favs - { 'movie', 'band'} WHERE id = 'jsmith';
+
+ Note that for removing multiple elements in a ``map``, you remove from it a ``set`` of keys.
+
+Lastly, TTLs are allowed for both ``INSERT`` and ``UPDATE``, but in both cases, the TTL set only applies to the newly
+inserted/updated elements. In other words::
+
+ UPDATE users USING TTL 10 SET favs['color'] = 'green' WHERE id = 'jsmith';
+
+will only apply the TTL to the ``{ 'color' : 'green' }`` record, the rest of the map remaining unaffected.
+
+.. _sets:
+
+Sets
+~~~~
+
+A ``set`` is a (sorted) collection of unique values. You can define a set column with::
+
+ CREATE TABLE images (
+ name text PRIMARY KEY,
+ owner text,
+ tags set<text> // A set of text values
+ );
+
+A set column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the set's
+old content, if any::
+
+ INSERT INTO images (name, owner, tags)
+ VALUES ('cat.jpg', 'jsmith', { 'pet', 'cute' });
+
+ UPDATE images SET tags = { 'kitten', 'cat', 'lol' } WHERE name = 'cat.jpg';
+
+Note that Scylla does not distinguish an empty set from a missing value,
+thus assigning an empty set (``{}``) to a set is the same as deleting it.
+
+Further, sets support:
+
+- Adding one or multiple elements (as this is a set, inserting an already existing element is a no-op)::
+
+ UPDATE images SET tags = tags + { 'gray', 'cuddly' } WHERE name = 'cat.jpg';
+
+- Removing one or multiple elements (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ UPDATE images SET tags = tags - { 'cat' } WHERE name = 'cat.jpg';
+
+Lastly, as for :ref:`maps <maps>`, TTLs, if used, only apply to the newly inserted values.
+
+.. _lists:
+
+Lists
+~~~~~
+
+.. note:: As mentioned above and further discussed at the end of this section, lists have limitations and specific
+ performance considerations that you should take into account before using them. In general, if you can use a
+ :ref:`set <sets>` instead of a list, always prefer a set.
+
+
+A ``list`` is an ordered list of values (not necessarily unique). You can define a list column with::
+
+ CREATE TABLE plays (
+ id text PRIMARY KEY,
+ game text,
+ players int,
+ scores list<int> // A list of integers
+ );
+
+A list column can be assigned new contents with either ``INSERT`` or ``UPDATE``,
+as in the following examples. In both cases, the new contents replace the list's
+old content, if any::
+
+ INSERT INTO plays (id, game, players, scores)
+ VALUES ('123-afde', 'quake', 3, [17, 4, 2]);
+
+ UPDATE plays SET scores = [ 3, 9, 4] WHERE id = '123-afde';
+
+Note that Scylla does not distinguish an empty list from a missing value,
+thus assigning an empty list (``[]``) to a list is the same as deleting it.
+
+Further, lists support:
+
+- Appending and prepending values to a list::
+
+ UPDATE plays SET players = 5, scores = scores + [ 14, 21 ] WHERE id = '123-afde';
+ UPDATE plays SET players = 6, scores = [ 3 ] + scores WHERE id = '123-afde';
+
+- Setting the value at a particular position in the list. This implies that the list has a pre-existing element for that
+ position or an error will be thrown that the list is too small::
+
+ UPDATE plays SET scores[1] = 7 WHERE id = '123-afde';
+
+- Removing an element by its position in the list. This implies that the list has a pre-existing element for that position,
+ or an error will be thrown that the list is too small. Further, as the operation removes an element from the list, the
+ list size will be diminished by 1, shifting the position of all the elements following the one deleted::
+
+ DELETE scores[1] FROM plays WHERE id = '123-afde';
+
+- Deleting *all* the occurrences of particular values in the list (if a particular element doesn't occur at all in the
+ list, it is simply ignored, and no error is thrown)::
+
+ UPDATE plays SET scores = scores - [ 12, 21 ] WHERE id = '123-afde';
+
+.. warning:: The append and prepend operations are not idempotent by nature. So, in particular, if one of these operation
+ timeouts, then retrying the operation is not safe, and it may (or may not) lead to appending/prepending the value
+ twice.
+
+.. warning:: Setting and removing an element by position and removing occurrences of particular values incur an internal
+ *read-before-write*. They will thus run more slowly and take more resources than usual updates (with the exclusion
+ of conditional write that have their own cost).
+
+Lastly, as for :ref:`maps <maps>`, TTLs, when used, only apply to the newly inserted values.
+
+.. _udts:
+
+User-Defined Types
+^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 3.2 Scylla Open Source
+
+CQL support the definition of user-defined types (UDT for short). Such a type can be created, modified and removed using
+the :token:`create_type_statement`, :token:`alter_type_statement` and :token:`drop_type_statement` described below. But
+once created, a UDT is simply referred to by its name:
+
+.. code-block::
+
+ user_defined_type: `udt_name`
+ udt_name: [ `keyspace_name` '.' ] `identifier`
+
+
+Creating a UDT
+~~~~~~~~~~~~~~
+
+.. versionchanged:: 3.2 Scylla Open Source
+
+.. note:: If you are using Scylla Open Source 3.1.x (and prior) or Scylla Enterprise (any version), UDTs must be **frozen** - meaning you cannot update individual components of the UDT value. The whole value must be overwritten. Starting with Scylla Open Source 3.2, UDTs that are not in a collection **can be non-frozen**.
+
+Creating a new user-defined type is done using a ``CREATE TYPE`` statement defined by:
+
+.. code-block::
+
+ create_type_statement: CREATE TYPE [ IF NOT EXISTS ] `udt_name`
+ : '(' `field_definition` ( ',' `field_definition` )* ')'
+ field_definition: `identifier` `cql_type`
+
+A UDT has a name (``udt_name``), which is used to declare columns of that type and is a set of named and typed fields. The ``udt_name`` can be any
+type, including collections or other UDTs. UDTs and collections inside collections must always be frozen (no matter which version of Scylla you are using).
+
+For example::
+
+ CREATE TYPE full_name (
+ first text,
+ last text
+ );
+
+
+ CREATE TYPE phone (
+ country_code int,
+ number text,
+ );
+
+ CREATE TYPE address (
+ street text,
+ city text,
+ zip text,
+ phones map<text, frozen<phone>>
+ );
+
+
+ CREATE TABLE superheroes (
+ name frozen<full_name> PRIMARY KEY,
+ home frozen<address>
+ );
+
+.. note::
+
+ - Attempting to create an already existing type will result in an error unless the ``IF NOT EXISTS`` option is used. If it is used, the statement will be a no-op if the type already exists.
+ - A type is intrinsically bound to the keyspace in which it is created and can only be used in that keyspace. At creation, if the type name is prefixed by a keyspace name, it is created in that keyspace. Otherwise, it is created in the current keyspace.
+ - As of Scylla Open Source 3.2, UDTs not inside collections do not have to be frozen, but in all versions prior to Scylla Open Souce 3.2, and in all Scylla Enterprise versions, UDTs **must** be frozen.
+
+
+A non-frozen UDT example with Scylla Open Source 3.2 and higher::
+
+ CREATE TYPE ut (a int, b int);
+ CREATE TABLE cf (a int primary key, b ut);
+
+Same UDT in versions prior::
+
+ CREATE TYPE ut (a int, b int);
+ CREATE TABLE cf (a int primary key, b frozen<ut>);
+
+UDT literals
+~~~~~~~~~~~~
+
+Once a user-defined type has been created, value can be input using a UDT literal:
+
+.. code-block::
+
+ udt_literal: '{' `identifier` ':' `term` ( ',' `identifier` ':' `term` )* '}'
+
+In other words, a UDT literal is like a :ref:`map <maps>` literal but its keys are the names of the fields of the type.
+For instance, one could insert into the table defined in the previous section using::
+
+
+ INSERT INTO superheroes (name, home)
+ VALUES ({first: 'Buffy', last: 'Summers'},
+ {street: '1630 Revello Drive',
+ city: 'Sunnydale',
+ phones: { 'land-line' : { country_code: 1, number: '1234567890'},
+ 'fax' : { country_code: 1, number: '10000000'}}
+ }
+ );
+
+ INSERT INTO superheroes (name, home)
+ VALUES ({first: 'Al', last: 'Bundy'},
+ {street: '9764 Jeopardy Lane',
+ city: 'Chicago'});
+
+To be valid, a UDT literal should only include fields defined by the type it is a literal of, but it can omit some fields
+(in which case those will be ``null``).
+
+
+You can use UDT in a WHERE clause of a SELECT statement as follow::
+
+ SELECT * from superheroes WHERE name={first: 'Al', last: 'Bundy'};
+
+result::
+
+ name | home
+ ------------------------------+--------------------------------------------------------------------------
+ {first: 'Al', last: 'Bundy'} | {street: '9764 Jeopardy Lane', city: 'Chicago', zip: null, phones: null}
+
+
+
+Note that if you provide a subset of the UDT, for example, just the ``first`` name in the example below, **null** will be used for the missing values.
+For example::
+
+ SELECT * from superheroes WHERE name={first: 'Al', last: 'Bundy'};
+
+result::
+
+ name | home
+ ------+------
+
+ (0 rows)
+
+
+Altering a UDT
+~~~~~~~~~~~~~~
+
+An existing user-defined type can be modified using an ``ALTER TYPE`` statement:
+
+.. code-block::
+
+ alter_type_statement: ALTER TYPE `udt_name` `alter_type_modification`
+ alter_type_modification: ADD `field_definition`
+ : | RENAME `identifier` TO `identifier` ( `identifier` TO `identifier` )*
+
+You can:
+
+- Add a new field to the type (``ALTER TYPE address ADD country text``). That new field will be ``null`` for any values
+ of the type created before the addition.
+- Rename the fields of the type (``ALTER TYPE address RENAME zip TO zipcode``).
+
+Dropping a UDT
+~~~~~~~~~~~~~~
+
+You can drop an existing user-defined type using a ``DROP TYPE`` statement:
+
+.. code-block::
+
+ drop_type_statement: DROP TYPE [ IF EXISTS ] `udt_name`
+
+Dropping a type results in the immediate, irreversible removal of that type. However, attempting to drop a type that is
+still in use by another type, table or function will result in an error.
+
+If the type dropped does not exist, an error will be returned unless ``IF EXISTS`` is used, in which case the operation
+is a no-op.
+
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also supports tuples and tuple types (where the elements can be of different types). Functionally, tuples can be
+thought as anonymous UDTs with anonymous fields. Tuple types and tuple literals are defined by:
+
+.. code-block::
+
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always ``frozen<tuple>`` (without the need of the
+`frozen` keyword), and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always provide values for all the components of the tuple type (some of
+those values can be null, but they need to be explicitly declared as so).
+
+.. .. _custom-types:
+
+.. Custom Types
+.. ^^^^^^^^^^^^
+
+.. .. note:: Custom types exists mostly for backward compatiliby purposes and their usage is discouraged. Their usage is
+.. complex, not user friendly and the other provided types, particularly :ref:`user-defined types <udts>`, should almost
+.. always be enough.
+
+.. A custom type is defined by:
+
+.. .. code-block::
+
+.. custom_type: `string`
+
+.. A custom type is a :token:`string` that contains the name of Java class that extends the server side ``AbstractType``
+.. class and that can be loaded by Apache Cassandra (it should thus be in the ``CLASSPATH`` of every node running Cassandra). That
+.. class will define what values are valid for the type and how the time sorts when used for a clustering column. For any
+.. other purpose, a value of a custom type is the same than that of a ``blob``, and can in particular be input using the
+.. :token:`blob` literal syntax.
+
+.. include:: /rst_include/apache-cql-return-index.rst
+
+.. include:: /rst_include/apache-copyrights.rst
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
diff --git a/docs/getting-started/x-mark-16.png b/docs/getting-started/x-mark-16.png
--- a/docs/getting-started/x-mark-16.png
+++ b/docs/getting-started/x-mark-16.png
null
diff --git a/docs/glossary.rst b/docs/glossary.rst
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -0,0 +1,178 @@
+.. _glossary:
+
+=====================
+Glossary
+=====================
+
+.. glossary::
+ :sorted:
+
+ Bootstrap
+ When a new node is added to a cluster, the bootstrap process ensures that the data in the cluster is automatically redistributed to the new node. A new node in this case is an empty node without system tables or data. See :ref:`bootstrap <temporary-fallback-to-stcs>`.
+
+ Anti-entropy
+ A state where data is in order and organized. Scylla has processes in place to make sure that data is antientropic where all replicas contain the most recent data and that data is consistent between replicas. See :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index>`.
+
+ CAP Theorem
+ The CAP Theorem is the notion that **C** (Consistency), **A** (Availability) and **P** (Partition Tolerance) of data are mutually dependent in a distributed system. Increasing any 2 of these factors will reduce the third. Scylla chooses availability and partition tolerance over consistency. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Cluster
+ One or multiple Scylla nodes, acting in concert, which own a single contiguous token range. State is communicated between nodes in the cluster via the Gossip protocol. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Clustering Key
+ A single or multi-column clustering key determines a row’s uniqueness and sort order on disk within a partition. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Column Family
+ See :term:`table<Table>`.
+
+ Compaction
+ The process of reading several SSTables, comparing the data and time stamps and then writing one SSTable containing the merged, most recent, information. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Compaction Strategy
+ Determines which of the SSTables will be compacted, and when. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Consistency Level (CL)
+ A dynamic value which dictates the number of replicas (in a cluster) that must acknowledge a read or write operation. This value is set by the client on a per operation basis. For the CQL Shell, the consistency level defaults to ONE for read and write operations. See :doc:`Consistency Levels </getting-started/consistency>`.
+
+ Quorum
+ Quorum is a *global* consistency level setting across the entire cluster including all data centers. See :doc:`Consistency Levels </getting-started/consistency>`.
+
+ Date-tiered compaction strategy (DTCS)
+ :abbr:`DTCS (Date-tiered compaction strategy)` is designed for time series data, but should not be used. Use :term:`Time-Window Compaction Strategy`. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Entropy
+ A state where data is not consistent. This is the result when replicas are not synced and data is random. Scylla has measures in place to be antientropic. See :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index>`.
+
+ Eventual Consistency
+ In Scylla, when considering the :term:`CAP Theorem <CAP Theorem>`, availability and partition tolerance are considered a higher priority than consistency.
+
+ Hint
+ A short record of a write request that is held by the co-ordinator until the unresponsive node becomes responsive again, at which point the write request data in the hint is written to the replica node. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Hinted Handoff
+ Reduces data inconsistency which can occur when a node is down or there is network congestion. In Scylla, when data is written and there is an unresponsive replica, the coordinator writes itself a hint. When the node recovers, the coordinator sends the node the pending hints to ensure that it has the data it should have received. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Idempotent
+ Denoting an element of a set which is unchanged in value when multiplied or otherwise operated on by itself. :doc:`Scylla Counters </using-scylla/counters>` are not indepotent because in the case of a write failure, the client cannot safely retry the request.
+
+ JBOD
+ JBOD or Just another Bunch Of Disks is a non-raid storage system using a server with multiple disks in order to instantiate a separate file system per disk. The benefit is that if a single disk fails, only it needs to be replaced and not the whole disk array. The disadvantage is that free space and load may not be evenly distributed. See the :ref:`FAQ <faq-raid0-required>`.
+
+ Keyspace
+ A collection of tables with attributes which define how data is replicated on nodes. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Key Management Interoperability Protocol (KMIP)
+ :abbr:`KMIP (Key Management Interoperability Protocol)` is a communication protocol that defines message formats for storing keys on a key management server (KMIP server). You can use a KMIP server to protect your keys when using Encryption at Rest. See :doc:`Encryption at Rest</operating-scylla/security/encryption-at-rest/>`.
+
+ Leveled compaction strategy (LCS)
+ :abbr:`LCS (Leveled compaction strategy)` uses small, fixed-size (by default 160 MB) SSTables divided into different levels. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Log-structured-merge (LSM)
+ A technique of keeping sorted files and merging them. LSM is a data structure that maintains key-value pairs. See :doc:`Compaction </kb/compaction>`
+
+ Logical Core (lcore)
+ A hyperthreaded core on a hyperthreaded system, or a physical core on a system without hyperthreading.
+
+ MemTable
+ An in-memory data structure servicing both reads and writes. Once full, the Memtable flushes to an :term:`SSTable<SSTable>`. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Mutation
+ A change to data such as column or columns to insert, or a deletion. See :doc:`Hinted Handoff </architecture/anti-entropy/hinted-handoff>`.
+
+ Node
+ A single installed instance of Scylla. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Nodetool
+ A simple command-line interface for administering a Scylla node. A nodetool command can display a given node’s exposed operations and attributes. Scylla’s nodetool contains a subset of these operations. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Primary Key
+ In a CQL table definition, the primary key clause specifies the partition key and optional clustering key. These keys uniquely identify each partition and row within a partition. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partition
+ A subset of data that is stored on a node and replicated across nodes. There are two ways to consider a partition. In CQL, a partition appears as a group of sorted rows, and is the unit of access for queried data, given that most queries access a single partition. On the physical layer, a partition is a unit of data stored on a node and is identified by a partition key. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partition Key
+ The unique identifier for a partition, a partition key may be hashed from the first column in the primary key. A partition key may also be hashed from a set of columns, often referred to as a compound primary key. A partition key determines which virtual node gets the first partition replica. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Partitioner
+ A hash function for computing which data is stored on which node in the cluster. The partitioner takes a partition key as an input, and returns a ring token as an output. By default Scylla uses the 64 bit Murmurhash3 function and this hash range is numerically represented as a signed 64bit integer, see :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Read Amplification
+ Excessive read requests which require many SSTables. RA is calculated by the number of disk reads per query. High RA occurs when there are many pages to read in order to answer a query. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Read Operation
+ A read operation occurs when an application gets information from an SSTable and does not change that information in any way. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Read Repair
+ An anti-entropy mechanism for read operations ensuring that replicas are updated with most recently updated data. These repairs run automatically, asynchronously, and in the background. See :doc:`Scylla Read Repair </architecture/anti-entropy/read-repair>`.
+
+ Reconciliation
+ A verification phase during a data migration where the target data is compared against original source data to ensure that the migration architecture has transferred the data correctly. See :doc:`Scylla Read Repair </architecture/anti-entropy/read-repair>`.
+
+ Repair
+ A process which runs in the background and synchronizes the data between nodes, so that eventually, all the replicas hold the same data. See :doc:`Scylla Repair </operating-scylla/procedures/maintenance/repair>`.
+
+ Replication
+ The process of replicating data across nodes in a cluster. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Replication Factor (RF)
+ The total number of replica nodes across a given cluster. An :abbr:`RF (Replication Factor)` of 1 means that the data will only exist on a single node in the cluster and will not have any fault tolerance. This number is a setting defined for each keyspace. All replicas share equal priority; there are no primary or master replicas. An RF for any table, can be defined for each :abbr:`DC (Data Center)`. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Shard
+ Each Scylla node is internally split into *shards*, an independent thread bound to a dedicated core.
+ Each shard of data is allotted CPU, RAM, persistent storage, and networking resources which it uses as efficiently as possible.
+ See `Scylla Shard per Core Architecture <https://www.scylladb.com/product/technology/shard-per-core-architecture/>`_ for more information.
+
+ Size-tiered compaction strategy
+ Triggers when the system has enough (four by default) similarly sized SSTables. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Snapshot
+ Snapshots in Scylla are an essential part of the backup and restore mechanism. Whereas in other databases a backup starts with creating a copy of a data file (cold backup, hot backup, shadow copy backup), in Scylla the process starts with creating a table or keyspace snapshot. See :doc:`Scylla Snapshots </kb/snapshots>`.
+
+ Snitch
+ The mapping from the IP addresses of nodes to physical and virtual locations, such as racks and data centers. There are several types of snitches. The type of snitch affects the request routing mechanism. See :doc:`Scylla Snitches </operating-scylla/system-configuration/snitch/>`.
+
+ Space amplification
+ Excessive disk space usage which requires that the disk be larger than a perfectly-compacted representation of the data (i.e., all the data in one single SSTable). SA is calculated as the ratio of the size of database files on a disk to the actual data size. High SA occurs when there is more disk space being used than the size of the data. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ SSTable
+ A concept borrowed from Google Big Table, SSTables or Sorted String Tables store a series of immutable rows where each row is identified by its row key. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`. The SSTable format is a persistent file format. See :doc:`Scylla SSTable Format</architecture/sstable/index>`.
+
+ Table
+ A collection of columns fetched by row. Columns are ordered by Clustering Key. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Time-window compaction strategy
+ TWCS is designed for time series data and replaced Date-tiered compaction. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Token
+ A value in a range, used to identify both nodes and partitions. Each node in a Scylla cluster is given an (initial) token, which defines the end of the range a node handles. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Token Range
+ The total range of potential unique identifiers supported by the partitioner. By default, each Scylla node in the cluster handles 256 token ranges. Each token range corresponds to a Vnode. Each range of hashes in turn is a segment of the total range of a given hash function. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Tombstone
+ A marker that indicates that data has been deleted. A large number of tombstones may impact read performance and disk usage, so an efficient tombstone garbage collection strategy should be employed. See :ref:`Tombstones GC options <ddl-tombstones-gc>`.
+
+ Tunable Consistency
+ The possibility for unique, per-query, Consistency Level settings. These are incremental and override fixed database settings intended to enforce data consistency. Such settings may be set directly from a CQL statement when response speed for a given query or operation is more important. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Virtual node
+ A range of tokens owned by a single Scylla node. Scylla nodes are configurable and support a set of :abbr:`Vnodes (virtual nodes)`. In legacy token selection, a node owns one token (or token range) per node. With Vnodes, a node can own many tokens or token ranges; within a cluster, these may be selected randomly from a non-contiguous set. In a Vnode configuration, each token falls within a specific token range which in turn is represented as a Vnode. Each Vnode is then allocated to a physical node in the cluster. See :doc:`Ring Architecture </architecture/ringarchitecture/index>`.
+
+ Write Amplification
+ Excessive compaction of the same data. :abbr:`WA (Write amplification)` is calculated by the ratio of bytes written to storage versus bytes written to the database. High WA occurs when there are more bytes/second written to storage than are actually written to the database. See :doc:`Compaction Strategies</architecture/compaction/compaction-strategies/>`.
+
+ Write Operation
+ A write operation occurs when information is added or removed from an SSTable. See :doc:`Fault Tolerance </architecture/architecture-fault-tolerance>`.
+
+ Reshard
+ Splitting an SSTable, that is owned by more than one shard (core), into SSTables that are owned by a single shard. For example: when restoring data from a different server, importing SSTables from Apache Cassandra, or changing the number of cores in a machine (upscale).
+
+ Reshape
+ Rewrite a set of SSTables to satisfy a compaction strategy’s criteria. For example, restoring data from an old backup or before the strategy update.
+
+ Shedding
+ Dropping requests to protect the system. This will occur if the request is too large or exceeds the max number of concurrent requests per shard.
+
+ Dummy Rows
+ Cache dummy rows are entries in the row set, which have a clustering position, although they do not represent CQL rows written by users. Scylla cache uses them to mark boundaries of population ranges, to represent the information that the whole range is complete, and there is no need to go to sstables to read the gaps between existing row entries when scanning.
diff --git a/docs/kb/IP_FWD1.png b/docs/kb/IP_FWD1.png
--- a/docs/kb/IP_FWD1.png
+++ b/docs/kb/IP_FWD1.png
null
diff --git a/docs/kb/Nat_Config.png b/docs/kb/Nat_Config.png
--- a/docs/kb/Nat_Config.png
+++ b/docs/kb/Nat_Config.png
null
diff --git a/docs/kb/_common/kb-article-template.rst b/docs/kb/_common/kb-article-template.rst
--- a/docs/kb/_common/kb-article-template.rst
+++ b/docs/kb/_common/kb-article-template.rst
@@ -0,0 +1,48 @@
+==============================
+Title in Title Caps
+==============================
+
+.. your title should be something customers will search for.
+
+**Topic: subject**
+
+.. Give a subtopic for the title (User Management, Security, Drivers, Automation, Optimization, Schema management, Data Modeling, etc.)
+
+**Learn: topic**
+
+.. in 1-3 words what will users learn by reading this article?
+
+**Audience: Scylla administrators**
+
+.. Choose (Application Developer, Scylla Administrator, Internal, All)
+
+Synopsis
+--------
+
+.. What issue, solution, or problem does this article address
+
+.. TOC for long articles, for short articles you can delete the next 3 lines
+
+
+.. add the rest of your content
+
+Heading 1
+---------
+
+
+Heading 2
+^^^^^^^^^
+
+
+Heading 3
+.........
+
+
+Additional References
+---------------------
+
+* link to reference `Red Hat Enterprise Linux
+ 7 <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/index.html>`__ for example
+
+
+.. add additional resources using the format above, or use other formats. You can get syntax help here: //www.sphinx-doc.org/en/master/
\ No newline at end of file
diff --git a/docs/kb/cdc-experimental-upgrade.rst b/docs/kb/cdc-experimental-upgrade.rst
--- a/docs/kb/cdc-experimental-upgrade.rst
+++ b/docs/kb/cdc-experimental-upgrade.rst
@@ -0,0 +1,27 @@
+===============================
+Upgrading from experimental CDC
+===============================
+
+If you used CDC in Scylla 4.2 or earlier by enabling the experimental feature and you upgrade to 4.3, you must perform additional steps for CDC to work properly.
+
+First, if you enabled CDC on any table (using ``with cdc = { ... }``), you should stop all writes to this table. Then disable CDC before the upgrade:
+
+.. code-block:: none
+
+ alter table ks.t with cdc = {'enabled': false};
+
+.. caution::
+
+ This will delete the CDC log table associated with this table - in this example, ``ks.t_scylla_cdc_log``.
+
+This should work even if you already upgraded, but preferably disable CDC on all tables before the upgrade.
+
+After disabling CDC and finishing the upgrade you can safely reenable it.
+
+The next step is running ``nodetool checkAndRepairCdcStreams``. Up to this point, Scylla may have periodically reported the following errors in its logs:
+
+.. code-block:: none
+
+ cdc - Could not retrieve CDC streams with timestamp {...} upon gossip event. Reason: "std::runtime_error (Could not find CDC generation with timestamp ... in distributed system tables (current time: ...), even though some node gossiped about it.)". Action: not retrying.
+
+After running the ``nodetool`` command the errors should not appear anymore. If they do, please open an issue.
diff --git a/docs/kb/compaction-incremental.png b/docs/kb/compaction-incremental.png
--- a/docs/kb/compaction-incremental.png
+++ b/docs/kb/compaction-incremental.png
null
diff --git a/docs/kb/compaction-leveled.png b/docs/kb/compaction-leveled.png
--- a/docs/kb/compaction-leveled.png
+++ b/docs/kb/compaction-leveled.png
null
diff --git a/docs/kb/compaction-size-tiered.png b/docs/kb/compaction-size-tiered.png
--- a/docs/kb/compaction-size-tiered.png
+++ b/docs/kb/compaction-size-tiered.png
null
diff --git a/docs/kb/compaction.rst b/docs/kb/compaction.rst
--- a/docs/kb/compaction.rst
+++ b/docs/kb/compaction.rst
@@ -0,0 +1,249 @@
+Compaction
+==========
+
+
+This document gives a high level overview of Compaction, focusing on what compaction is, and how it works. There is a different document that covers the :doc:`CQL syntax </getting-started/compaction>` for setting a compaction strategy. There is also another document, :doc:`Compaction Strategy Matrix </architecture/compaction/compaction-strategies>`, that covers how to decide which strategy works best.
+
+How Scylla Writes Data
+----------------------
+
+Scylla’s write path follows the well-known **Log Structured Merge (LSM)** design for efficient writes that are immediately available for reads. Scylla is not the first project to use this method. Popular projects to use this method include Lucene Search Engine, Google BigTable, and Apache Cassandra.
+
+Scylla writes its updates to a :term:`memory table (MemTable)<MemTable>`, and when that becomes too big, it is flushed to a new file. This file is sorted to make it easy to search and later merge. This is why the tables are known as Sorted String Tables or :term:`SSTables<SSTable>`.
+
+.. image:: write-path-image-memtable-sstable.png
+
+In time, two major problems start to appear. First, data in one SSTable which is later modified or deleted in another SSTable wastes space as both tables are present in the system. Second, when data is split across many SSTables, read requests are processed slower as many SSTables need to be read. Scylla mitigates the second problem by using a bloom filter and other techniques to avoid reading from SSTables that do not include the desired partition. However, as the number of SSTables grows, inevitably so do the number of disk blocks from which we need to read on every read query. For these reasons, as soon as enough SSTables have accumulated, Scylla performs a :term:`compaction<Compaction>`.
+
+
+Compaction Overview
+-------------------
+
+Compaction merges several SSTables into new SSTable(s) which contain(s) only the live data from the input SSTables. Merging several sorted files to get a sorted result is an efficient process, and this is the main reason why SSTables are kept sorted.
+
+There are two types of compactions:
+
+* Minor Compaction
+ Scylla automatically triggers a compaction of some SSTables, according to a :term:`compaction strategy<Compaction Strategy>` (as described below). This is the recommended method.
+
+* Major Compaction
+ A user triggers (using nodetool) a compaction over all SSTables, merging the individual tables according to the selected compaction strategy.
+
+.. caution:: It is always best to allow Scylla to automatically run minor compactions. Major compactions can exhaust resources, increase operational costs, and take up valuable disk space. This requires you to have 50% more disk space than your data unless you are using `Incremental compaction strategy (ICS)`_.
+
+View Compaction Statistics
+--------------------------
+
+Scylla has tools you can use to see the status of your compactions. These include nodetool (:doc:`compactionhistory </operating-scylla/nodetool-commands/compactionhistory>` and :doc:`compactionstats </operating-scylla/nodetool-commands/compactionstats>`) and the Grafana dashboards which are part of the `Scylla Monitoring Stack <https://monitoring.docs.scylladb.com/>`_ which display the compaction statistics on a per cluster and per node basis. Compaction errors can be seen in the :ref:`logs <manager-2.1-logging-settings>`.
+
+Compaction strategy
+-------------------
+
+A compaction strategy is what determines which of the SSTables will be compacted, and when. The following compaction strategies are available and are described in greater detail below. For a matrix which compares each strategy to its workload, refer to :doc:`Compaction Strategy Matrix </architecture/compaction/compaction-strategies>`
+
+* `Size-tiered compaction strategy (STCS)`_ - (default setting) triggered when the system has enough similarly sized SSTables.
+* `Leveled compaction strategy (LCS)`_ - the system uses small, fixed-size (by default 160 MB) SSTables divided into different levels and lowers both Read and Space Amplification.
+* `Incremental compaction strategy (ICS)`_ - Available for Enterprise customers, uses runs of sorted, fixed size (by default 1 GB) SSTables in a similar way that LCS does, organized into size-tiers, similar to STCS size-tiers. If you are an Enterprise customer ICS is an updated strategy meant to replace STCS. It has the same read and write amplification, but has lower space amplification due to the reduction of temporary space overhead is reduced to a constant manageable level.
+* `Time-window compaction strategy (TWCS)`_ - designed for time series data and puts data in time order. This strategy replaced Date-tiered compaction. TWCS uses STCS to prevent accumulating SSTables in a window not yet closed. When the window closes, TWCS works towards reducing the SSTables in a time window to one.
+* `Date-tiered compaction strategy (DTCS)`_ - designed for time series data, but TWCS should be used instead.
+
+How to Set a Compaction Strategy
+................................
+
+Compaction strategies are set as part of the ``CREATE`` or ``ALTER`` statement when creating or altering tables. Refer to the :doc:`CQL syntax </getting-started/compaction>` for details.
+
+.. caution:: Changing the parameters for compaction strategies or changing from one strategy to another (using the ``ALTER`` statement) can create issues. See `Changing Compaction Strategies or Properties`_ for more information.
+
+.. _size-tiered-compaction-strategy-stcs:
+
+Size-tiered Compaction Strategy (STCS)
+--------------------------------------
+
+The premise of ``SizeTieredCompactionStrategy`` (STCS) is to merge SSTables of approximately the same size.
+All SSTables are put into different buckets depending on their size.
+An SSTable is added to an existing bucket if size of the SSTable is within the parameters: :ref:`bucket_low <stcs-options>` and :ref:`bucket_high <stcs-options>`, which is based on calculating the current average size of the SSTables already in the bucket.
+
+This will create several buckets and when the threshold number of tables(``min_threshold``) within a bucket is reached, the tables in that bucket are compacted.
+Following the compaction, the tables are merged, resulting in one larger SSTable. As time progresses and several large SSTables have accumulated, they will be merged to form one even-larger SSTable and so on.
+
+This means that the system has several size tiers/buckets (small SSTables, large SSTables, even-larger SSTables) and in each tier, there is roughly the same number of SSTables. When one tier is full (the threshold has been reached), the system merges all its tables to create one SSTable which falls roughly into the next size tier.
+
+.. image:: compaction-size-tiered.png
+
+.. _leveled-compaction-strategy-lcs:
+
+Leveled Compaction Strategy (LCS)
+---------------------------------
+
+Leveled Compaction uses small, fixed-size (by default 160 MB) SSTables divided into different levels. Each level represents a run of a number of SSTables.
+
+A run of SSTables
+.................
+
+A **run** is a :term:`log-structured-merge (LSM)<Log-structured-merge (LSM)>` term for a large SSTable split into several smaller SSTables. In other words, a run is a collection of SSTables with non-overlapping key ranges. The benefit of a run is that when a compaction is done, only parts of it (small individual SSTables) are compacted and deleted. Following a compaction, SSTables are smaller and there is no need to compact a huge SSTable all at once.
+
+.. image:: compaction-leveled.png
+
+
+The compaction method works as follows:
+
+1. New SSTables (created from MemTables) are created in **Level 0**. All other levels are each a run of SSTables, of exponentially increasing size as follows:
+
+ - **Level 1** is a run of 10 SSTables (160 MB each table * 10)
+ - **Level 2** is a run of 100 SSTables (160 MB each table * 100), etc.
+
+2. When there are 4 SSTables in Level 0, they are compacted with the 10 SSTables in Level 1. This compaction works as follows:
+
+ - Read in parallel 4 SSTables in level 0 and 10 in Level 1.
+ - Write new SSTables for Level 1 (replacing the 10 old tables which were compacted).
+ - Instead of creating one large SSTable, several SSTables are written as follows: One SSTable is created. When it reaches the size limit (160 MB), a new table starts. As the data is merged on the sorted keys, this generates a run (see `A run of SSTables`_), with non-overlapping key ranges.
+
+3. If after the compaction from Level 0 into Level 1, if there are at least 10 SSTables in Level 1, the excess SSTables from Level 1 are compacted and put into Level 2 as follows:
+
+ - Take one SSTable from Level 1 (this SSTable will be deleted after the compaction)
+ - Look at this SSTable’s key range, and find all SSTables in Level 2 which overlap with it. Typically, there are about 12 of these (the Level 1 SSTable spans roughly 1/10th of the keys, while each Level 2 SSTable spans roughly 1/100th of the keys, so 10 Level 2 SSTables will overlap the Level 1 SSTable’s range, plus two more on the edges).
+ - As before, compact the 1 SSTable from Level 1 and the 12 SSTables from Level 2 and create new SSTables in Level 2 (and delete the 1+12 original SSTables).
+ - If after this compaction of Level 1 into Level 2, there are excess SSTables in Level 2 (as Level 2 can only take 100 tables), merge them into Level 3.
+
+.. _temporary-fallback-to-stcs:
+
+Temporary Fallback to STCS
+..........................
+
+When new data is written very quickly, the Leveled Compaction strategy may be temporarily unable to keep up with the demand. This can result in an accumulation of a large number of SSTables in L0 which in turn create very slow reads as all read requests read from all SSTables in L0. So as an emergency measure, when the number of SSTables in L0 grows to 32, LCS falls back to STCS to quickly reduce the number of SSTables in L0. Eventually, LCS will move this data again to fixed-sized SSTables in higher levels.
+
+Likewise, when :term:`bootstrapping<Bootstrap>` a new node, SSTables are streamed from other nodes. The level of the remote SSTable is kept to avoid many compactions until after the bootstrap is done. During the bootstrap, the new node receives regular write requests while it is streaming the data from the remote node. Just like any other write, these writes are flushed to L0. If Scylla did an LCS compaction on these L0 SSTables and created SSTables in higher level, this could have blocked the remote SSTables from going to the correct level (remember that SSTables in a run must not have overlapping key ranges). To remedy this from happening, Scylla compacts the tables using STCS only in L0 until the bootstrap process is complete. Once done, all resumes as normal under LCS.
+
+.. _incremental-compaction-strategy-ics:
+
+Incremental Compaction Strategy (ICS)
+-------------------------------------
+
+.. versionadded:: 2019.1.4 Scylla Enterprise
+
+.. include:: /rst_include/enterprise-only-note.rst
+
+One of the issues with Size-tiered compaction is that it needs temporary space because SSTables are not removed until they are fully compacted. ICS takes a different approach and splits each large SSTable into a run of sorted, fixed-size (by default 1 GB) SSTables (a.k.a. fragments) in the same way that LCS does, except it treats the entire run and not the individual SSTables as the sizing file for STCS. As the run-fragments are small, the SSTables compact quickly, allowing individual SSTables to be removed as soon as they are compacted. This approach uses low amounts of memory and temporary disk space.
+
+ICS uses the same philosophy as STCS, where the SSTables are sorted in buckets according to their size. However, unlike STCS, ICS compaction uses SSTable runs as input, and produces a new run as output. It doesn't matter if a run is composed of only one fragment that could have come from STCS migration. From an incremental compaction perspective, everything is a run.
+
+The strategy works as follows:
+
+#. ICS looks for candidates for compaction that are similar in size. These candidates are called ``Input Runs``.
+
+ * The input runs may contain one or more SSTables each.
+
+#. ICS compacts two or more similar-sized input runs into a single ``Output run`` (* See note_ ).
+#. Incremental Compaction progressively works on two or more fragments at a time, one from each input run.
+
+ * It reads mutations from all input fragments and merges them together into a single output fragment.
+ * As long as the resulting fragment is smaller than the ``sstable_size_in_mb``, no further action is needed.
+ * If the fragment is larger than the ``sstable_size_in_mb``:
+
+ 1. Stop when the size threshold is reached, and seal the output fragment.
+ 2. Create a new run fragment and continue compacting the remaining input fragments, until the size threshold is reached.
+ 3. When an input fragment is exhausted, take it out of the list of SSTables to compact, and delete it from disk.
+ 4. Repeat until there are no input fragments left.
+
+#. Take all of the output fragments and feed them back into compaction as an SSTable run.
+#. Stop when all fragments from input runs were exhausted and released.
+
+.. _note:
+.. note:: To prevent data resurrection in case scylla crashes in the middle of compaction, ICS may possibly write an auxiliary run containing purgeable tombstones in addition to the output run containing live data.
+ These tombstones are kept on disk while there are SSTables containing data that the tombstones may shadow. Once compaction is done, deleting all shadowed data from all SSTables, the purgeable tombstones are purged and the SSTables holding them are removed from storage.
+
+.. image:: ics-incremental-compaction.png
+
+Incremental compaction as a solution for temporary space overhead in STCS
+.........................................................................
+
+We fixed the temporary space overhead on STCS by applying the incremental compaction approach to it, which resulted in the creation of Incremental Compaction Strategy (ICS). The compacted SSTables, that become increasingly larger over time with STCS, are replaced with sorted runs of SSTable fragments, together called “SSTable runs” – which is a concept borrowed from Leveled Compaction Strategy (LCS).
+
+Each fragment is a roughly fixed size (aligned to partition boundaries) SSTable and it holds a unique range of keys, a portion of the whole SSTable run. Note that as the SSTable-runs in ICS hold exactly the same data as the corresponding SSTables created by STCS, they become increasingly longer over time (holding more fragments), in the same way that SSTables grow in size with STCS, yet the ICS SSTable fragments’ size remains the same.
+
+For example, when compacting two SSTables (or SSTable runs) holding 7GB each: instead of writing up to 14GB into a single SSTable file, we’ll break the output SSTable into a run of 14 x 1GB fragments (fragment size is 1GB by default).
+
+.. image:: compaction-incremental.png
+
+.. _time-window-compactionstrategy-twcs:
+
+Time-window Compaction Strategy (TWCS)
+--------------------------------------
+
+Time-window compaction strategy was introduced as a replacement for `Date-tiered Compaction Strategy (DTCS)`_ for handling time series workloads. Time-Window Compaction Strategy compacts SSTables within each time window using `Size-tiered Compaction Strategy (STCS)`_. SSTables from different time windows are never compacted together.
+
+.. include:: /rst_include/warning-ttl-twcs.rst
+
+The strategy works as follows:
+
+1. A time window is configured. The window is determined by the compaction window size :ref:`compaction_window_size <twcs-options>` and the time unit (:ref:`compaction_window_unit <twcs-options>`).
+2. SSTables created within the time window are compacted using `Size-tiered Compaction Strategy (STCS)`_.
+3. Once a time window ends, take all SSTables which were created during the time window and compact the data into one SSTable.
+4. The final resulting SSTable is never compacted with other time-windows’ SSTables.
+
+With this explanation, if the time window was for one day, at the end of the day, the SSTables accumulated for that day only would be compacted into one SSTable.
+
+When time-series data gets out of order
+.......................................
+
+The primary motivation for TWCS is to separate data on disk by timestamp and to allow fully expired SSTables to drop more efficiently. This efficiency stops when data is written to SSTables out of order, with new data and old data in the same SSTable. Out of order data can appear in the same SSTable in two ways:
+
+* If the user mixes old data and new data in the traditional write path, the data is commingled in the MemTables and flushed into the same SSTable, where it will remain commingled.
+* If the user’s read requests for old data causes read repairs that pull the old data into the current MemTable. The data is commingled in the MemTables and flushed into the same SSTable, where it will remain commingled.
+
+While TWCS tries to minimize the impact of commingled data, users should attempt to avoid this behavior. Specifically, users should avoid queries that explicitly set the timestamp. It is recommended to run frequent repairs (which streams data in such a way that it does not become commingled), and disable background read repair by setting the table’s :ref:`read_repair_chance <create-table-general-options>` and :ref:`dclocal_read_repair_chance <create-table-general-options>` to ``0``.
+
+
+Date-tiered compaction strategy (DTCS)
+--------------------------------------
+
+Date-Tiered Compaction is designed for time series data. It is only suitable for time-series data. This strategy has been replaced by `Time-window compaction strategy (TWCS)`_.
+
+Date-tiered compaction strategy works as follows:
+
+* First it sorts the SSTables by time and then compacts adjacent (time-wise) SSTables.
+* This results in SSTables whose sizes increase exponentially as they grow older.
+
+For example, at some point we can have the last minute of data in one SSTable (by default, base_time_seconds = 60), another minute before that in another SSTable, then the 4 minutes before that in one SSTable, then the 4 minutes before that, then an SSTable of the 16 minutes before that, and so on. This structure can easily be maintained by compaction, very similar to size-tiered compaction. When there are 4 (the default value for min_threshold) small (one-minute) consecutive SSTables, they are compacted into one 4-minute SSTable. When there are 4 of the bigger SSTables one after another (time-wise), they are merged into a 16-minute SSTable, and so on.
+
+Antique SSTables older than ``max_SSTable_age_days`` (by default 365 days) are not compacted as doing these compactions would not be useful for most queries, the process would be very slow, and the compaction would require huge amounts of temporary disk space.
+
+
+Changing Compaction Strategies or Properties
+--------------------------------------------
+
+Changing the Threshold in LCS
+.............................
+
+There can be cases where, following a compaction, tables are created in a level which are not compacted for a considerable amount of time.
+For example, a user has tables which are using LCS. There are 5 levels of tables at present and the ``SSTable_size_in_mb`` is 5MB. The user changes this threshold to 160MB. Following this change, there is only enough data to actually get an L3 on the same node. The data in the SSTables in L4 will get starved and will not get compacted. To avoid this, LCS tries to include those starved high level SSTables in future compactions. If after been 25 compaction rounds, a level was not compacted, it is brought in to the next compaction.
+
+Changing to Time Window Compaction Strategy (TWCS)
+..................................................
+
+If you want to enable TWCS on existing data, you may consider running a major compaction first, placing all existing data into a single (old) window. Subsequent newer writes will then create typical SSTables as expected.
+
+Changing the Time Window in TWCS
+................................
+
+If you want to change the time window you can do so, but keep in mind that this change may trigger additional compactions as adjacent windows are joined together. If the window size is decreased (for example, from 24 hours to 12 hours), then the existing SSTables will not be modified. Note as well that TWCS can not split existing SSTables into multiple windows.
+
+
+Which Strategy is best to use
+-----------------------------
+Use the table in :ref:`Which strategy is best <which-strategy-is-best>` to determine the right strategy for your needs.
+
+
+
+
+References
+----------
+* :doc:`CQL Reference for Compaction </getting-started/compaction>`
+
+* :doc:`How to Choose a Compaction Strategy </architecture/compaction/compaction-strategies>`.
+
+* `Blog: Scylla’s Compaction Strategies Series: Write Amplification in Leveled Compaction <https://www.scylladb.com/2018/01/31/compaction-series-leveled-compaction/>`_
+
+* `Blog: Scylla’s Compaction Strategies Series: Space Amplification in Size-Tiered Compaction <https://www.scylladb.com/2018/01/17/compaction-series-space-amplification/>`_
+
+* Size Tiered: `Shrikant Bang’s Notes <https://shrikantbang.wordpress.com/2014/04/22/size-tiered-compaction-strategy-in-apache-cassandra/>`_
diff --git a/docs/kb/count-all-rows.rst b/docs/kb/count-all-rows.rst
--- a/docs/kb/count-all-rows.rst
+++ b/docs/kb/count-all-rows.rst
@@ -0,0 +1,23 @@
+====================================
+Counting all rows in a table is slow
+====================================
+
+**Audience: Scylla users**
+
+Trying to count all rows in a table using
+
+.. code-block:: cql
+
+ SELECT COUNT(1) FROM ks.table;
+
+often fails with **ReadTimeout** error.
+
+COUNT() is running a full-scan query on all nodes, which might take a long time to finish. Often the time is greater than Scylla query timeout.
+One way to bypass this in Scylla 4.4 or later is increasing the timeout for this query using the :ref:`USING TIMEOUT <using-timeout>` directive, for example:
+
+
+.. code-block:: cql
+
+ SELECT COUNT(1) FROM ks.table USING TIMEOUT 120s;
+
+You can also get an *estimation* of the number **of partitions** (not rows) with :doc:`nodetool tablestats </operating-scylla/nodetool-commands/tablestats>`
diff --git a/docs/kb/cqlsh-more.rst b/docs/kb/cqlsh-more.rst
--- a/docs/kb/cqlsh-more.rst
+++ b/docs/kb/cqlsh-more.rst
@@ -0,0 +1,19 @@
+=============================================
+CQL Query Does Not Display Entire Result Set
+=============================================
+
+**Audience: Scylla administrators**
+
+If you send a cqlsh query similar to:
+
+.. code-block:: none
+
+ SELECT * FROM 'keyspace.table' limit 100;
+
+and the results show a single row with ``--More--``, the ``--More--`` indicates that there are additional pages - if you click Enter, additional rows are displayed.
+
+As the query is using paging (from cqlsh by default page size is 100) - Scylla uses this information internally and will fetch internally page size results. Some of these may be discarded and not returned to you or the output may reveal blank pages where you will see the ``--More--`` prompt causing you to page through empty pages. Neither of these outputs is desired.
+
+If you need text result of this query as a single run, without the page delimiter, you can :ref:`turn off paging <cqlsh-paging>`.
+
+It is also recommended to turn ``tracing on`` (please keep the limit to 100 as well).
diff --git a/docs/kb/cqlsh-results.rst b/docs/kb/cqlsh-results.rst
--- a/docs/kb/cqlsh-results.rst
+++ b/docs/kb/cqlsh-results.rst
@@ -0,0 +1,29 @@
+
+================================================================
+When CQLSh query returns partial results with followed by "More"
+================================================================
+
+
+.. your title should be something customers will search for.
+
+**Topic: When results are missing from query**
+
+
+**Audience: Scylla administrators**
+
+Synopsis
+---------
+
+If you send a cqlsh query similar to:
+
+.. code-block:: none
+
+ SELECT * FROM 'keyspace.table' limit 100;
+
+and the results show a single row with ``--More``, the ``--More--`` indicates that there are additional pages - if you click Enter, additional rows are displayed.
+
+As the query is using paging (from cqlsh by default page size is 100) - Scylla uses this information internally and will fetch internally page size results. Some of these may be discarded and not returned to you or the output may reveal blank pages where you will see the ``more`` prompt causing you to page through empty pages. Neither of these outputs is desired.
+
+If you need this in query as a single result you can turn off paging and include paging off in the query.
+
+It is also recommended to turn tracing on (please keep the limit to 100 as well).
diff --git a/docs/kb/custom-user.rst b/docs/kb/custom-user.rst
--- a/docs/kb/custom-user.rst
+++ b/docs/kb/custom-user.rst
@@ -0,0 +1,55 @@
+Run Scylla and supporting services as a custom user:group
+=========================================================
+**Topic: Planning and setup**
+By default, Scylla runs as user ``scylla`` in group ``scylla``. The following procedure will allow you to use a custom user and group to run Scylla.
+1. Create the new user and update file permissions
+
+.. code-block:: sh
+
+ useradd test
+ groupadd test
+ usermod test -G test
+ chown -R test:test /var/lib/scylla
+
+2. Edit ``/etc/sysconfig/scylla-server`` and change the USER and GROUP
+
+.. code-block:: sh
+
+ USER=test
+ GROUP=test
+
+3. Edit ``/etc/systemd/system/multi-user.target.wants/scylla-server.service``
+
+.. code-block:: sh
+
+ User=test
+
+4. Edit ``/etc/systemd/system/multi-user.target.wants/node-exporter.service``
+
+.. code-block:: sh
+
+ User=test
+ Group=test
+
+5. Edit /usr/lib/systemd/system/scylla-jmx.service
+
+.. code-block:: sh
+
+ User=test
+ Group=test
+
+6. Reload the daemon settings and start Scylla and node_exporter
+
+.. code-block:: sh
+
+ systemctl daemon-reload
+ systemctl start scylla-server
+ systemctl start node-exporter
+
+At this point, all services should be started as test:test user:
+
+.. code-block:: sh
+
+ test 8760 1 11 14:42 ? 00:00:01 /usr/bin/scylla --log-to-syslog 1 --log-to-std ...
+ test 8765 1 12 14:42 ? 00:00:01 /opt/scylladb/jmx/symlinks/scylla-jmx -Xmx256m ...
+ test 13638 1 0 14:30 ? 00:00:00 /usr/bin/node_exporter --collector.interrupts
diff --git a/docs/kb/decode-stack-trace.rst b/docs/kb/decode-stack-trace.rst
--- a/docs/kb/decode-stack-trace.rst
+++ b/docs/kb/decode-stack-trace.rst
@@ -0,0 +1,151 @@
+=====================
+Decoding Stack Traces
+=====================
+
+**Topic: Decoding stack traces in Scylla logs**
+
+**Environment: Any Scylla setup on any supported OS**
+
+**Audience: All**
+
+Synopsis
+--------
+
+This article describes how to decode the stack traces found in Scylla logs.
+
+
+What are Stack Traces?
+----------------------
+
+Stack traces can appear in the logs due to various errors or in the course of regular database operation. It is useful to be able to decode the trace in order to understand what exactly happened. Decoding the stack trace requires the Debug binaries for the specific Scylla build and OS in use are installed.
+
+Note that sharing the stack trace as part of your support ticket or Github issue, helps the Scylla support team to understand the issue better.
+
+
+Install Debug Binary files
+--------------------------
+
+Install the Debug binaries according to your OS distribution
+
+.. tabs::
+
+ .. group-tab:: RPM based distributions
+
+ For Scylla Enterprise:
+
+ .. code-block:: none
+
+ yum install scylla-enterprise-debuginfo
+
+ For Scylla Open Source:
+
+ .. code-block:: none
+
+ yum install scylla-debuginfo
+
+ .. group-tab:: DEB based distributions
+
+ For Scylla Enterprise:
+
+ .. code-block:: none
+
+ apt-get install scylla-enterprise-server-dbg
+
+ For Scylla Open Source:
+
+ .. code-block:: none
+
+ apt-get install scylla-server-dbg
+
+
+Validate the debug binary file name
+-----------------------------------
+
+To later determine the actual debug binary, look in the ``/usr/lib/debug/`` directory
+for a file named scylla.debug.
+
+For example:
+
+.. code-block:: none
+
+ # find /usr/lib/debug/ | grep scylla.debug
+ /usr/lib/debug/usr/bin/scylla.debug
+
+Locate and Analyze the Logs
+----------------------------
+
+**Procedure**
+
+#. Copy the stack from the :doc:`system log </getting-started/logging>` and place it in a file (trace.txt, for example).
+
+ .. code-block:: none
+
+ Jul 14 16:56:50 hostname01 scylla: Aborting on shard 8.
+ Jul 14 16:56:50 hostname01 scylla: Backtrace:
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000688602
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a36fc
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a39a5
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000005a3a53
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libpthread.so.0+0x000000000000f6cf
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x0000000000036276
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x0000000000037967
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024ce37b
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024d2a47
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024df1d5
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000023dccec
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000023feac1
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024324b9
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000024357e4
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000001eace90
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000001eaf944
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000584ab6
+ Jul 14 16:56:50 hostname01 scylla: 0x0000000000584c71
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000006522ff
+ Jul 14 16:56:50 hostname01 scylla: 0x00000000006554e5
+ Jul 14 16:56:50 hostname01 scylla: 0x000000000073d3cd
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libpthread.so.0+0x0000000000007e24
+ Jul 14 16:56:50 hostname01 scylla: /lib64/libc.so.6+0x00000000000febac
+
+
+
+#. Locate the files for backtrace.
+
+ .. code-block:: shell
+
+ find . -name "scylla*.debug"
+
+ With Scylla 4.1 for example, returns:
+
+ .. code-block:: shell
+
+ /usr/lib/debug/opt/scylladb/libexec/scylla-4.1.1-0.20200703.1d9bbbc9577.x86_64.debug
+
+#. Run the decoder:
+
+ .. code-block:: none
+
+ ./seastar-addr2line -e /usr/lib/debug/usr/bin/scylla.debug -f trace.txt > trace_decoded.txt
+
+ ``trace_decoded.txt`` now contains the decoded version of the stack trace:
+
+ For example:
+
+ .. code-block:: none
+
+ void seastar::backtrace<seastar::backtrace_buffer::append_backtrace()::{lambda(seastar::frame)#1}>(seastar::backtrace_buffer::append_backtrace()::{lambda(seastar::frame)#1}&&) at /usr/src/debug/scylla-4.1.1/seastar/util/backtrace.hh:56
+ seastar::backtrace_buffer::append_backtrace() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:390
+ (inlined by) print_with_backtrace at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:411
+ seastar::print_with_backtrace(char const*) at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:418
+ sigabrt_action at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3939
+ (inlined by) operator() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3921
+ (inlined by) _FUN at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3917
+ ...
+
+ seastar::reactor::run_tasks(seastar::reactor::task_queue&) at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:2621
+ seastar::reactor::run_some_tasks() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3033
+ seastar::reactor::run_some_tasks() at /opt/scylladb/include/c++/7/chrono:377
+ (inlined by) seastar::reactor::run() at /usr/src/debug/scylla-4.1.1/seastar/core/reactor.cc:3180
+
+
+
+
diff --git a/docs/kb/disk-utilization.rst b/docs/kb/disk-utilization.rst
--- a/docs/kb/disk-utilization.rst
+++ b/docs/kb/disk-utilization.rst
@@ -0,0 +1,50 @@
+===============================
+Snapshots and Disk Utilization
+===============================
+
+**Topic: nodetool snapshot and disk space**
+
+**Learn: understand how nodetool snapshot utilizes disk space**
+
+**Audience: Scylla administrators**
+
+
+When you create a snapshot using :doc:`nodetool snapshot </operating-scylla/nodetool-commands/snapshot>` command, Scylla is not going to copy existing SStables to the snapshot directory as one could have expected. Instead, it is going to create hard links to them. While this may seem trivial, what should be noted is the following:
+
+* The snapshot disk space at first will start at zero and will grow to become equal to the size of the node data set when the snapshot was created. So at the beginning there will not be any significant increase in the disk space utilization.
+* While it may seem plausible to believe that the snapshot image is immediately created, the snapshot eventually grows to its expected size
+* Background compactions will delete data from SSTables as normal, but any table with a hard link (part of the snapshot) will not be deleted. This will take up disk space.
+* This in particular means that once you have created the snapshot, its “true size” begins at zero and will eventually become equal to the size of the node data set when the snapshot was created.
+
+
+In this example, a snapshot was created. As you can see, its ``True size`` value is 0 bytes:
+
+.. code-block:: none
+
+ nodetool listsnapshots
+ Snapshot Details:
+
+ Snapshot name Keyspace name Column family name True size Size on disk
+ 1574708464997 ks3 standard1 0 bytes 2.23 GB
+
+ Total TrueDiskSpaceUsed: 0 bytes
+
+After time, you can see its ``True size`` is the same as the space it utilizes on disk:
+
+.. code-block:: none
+
+ nodetool compact ks3
+ nodetool listsnapshots
+
+ Snapshot Details:
+ Snapshot name Keyspace name Column family name True size Size on disk
+ 1574708464997 ks3 standard1 2.23 GB 2.23 GB
+
+ Total TrueDiskSpaceUsed: 2.23 GiB
+
+.. note:: A major compaction makes the true snapshot size jump to the data size immediately as the old SSTables are being deleted.
+
+
+Additional References
+---------------------
+* :doc:`Nodetool Snapshoot </operating-scylla/nodetool-commands/snapshot>`
diff --git a/docs/kb/dpdk-hardware.rst b/docs/kb/dpdk-hardware.rst
--- a/docs/kb/dpdk-hardware.rst
+++ b/docs/kb/dpdk-hardware.rst
@@ -0,0 +1,37 @@
+DPDK mode
+=========
+**Topic: Planning and setup**
+
+**Learn: How to select networking hardware for Scylla**
+
+**Audience: Scylla administrators**
+
+Scylla is designed to use the Seastar framework, which uses the Data Plane Development Kit (DPDK) to drive NIC hardware directly, instead of relying on the kernel’s network stack. This provides an enormous performance boost for Scylla. Scylla and DPDK also rely on the Linux “hugepages” feature to minimize overhead on memory allocations. DPDK is supported on a variety of high-performance network devices.
+
+.. role:: raw-html(raw)
+ :format: html
+
++------+---------------------------------------------------+--------------------------------------+
+|Brand |Device | Status |
++======+===================================================+======================================+
+|Intel |ixgbe (82598..82599, X540, X550) | :raw-html:`<span class="icon-yes"/>` |
++------+---------------------------------------------------+--------------------------------------+
+|Intel |i40e (X710, XL710) | :raw-html:`<span class="icon-yes"/>` |
++------+---------------------------------------------------+--------------------------------------+
+
+Scylla RPM packages are built with DPDK support, but the package defaults to POSIX networking mode (see Administration Guide). To enable DPDK, edit ``/etc/sysconfig/scylla-server`` and edit the following lines:
+
+.. code-block:: ini
+
+ # choose following mode: virtio, dpdk, posix
+ NETWORK_MODE=posix
+
+ # Ethernet device driver (dpdk)
+ ETHDRV=
+
+Reference
+---------
+`DPDK: Supported NICs <http://dpdk.org/doc/nics>`_
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/flamegraph.rst b/docs/kb/flamegraph.rst
--- a/docs/kb/flamegraph.rst
+++ b/docs/kb/flamegraph.rst
@@ -0,0 +1,53 @@
+=====================================
+Debug your database with Flame Graphs
+=====================================
+
+Flame Graphs are used as a debugging tool to identify latency and the part of the execution path that takes most of the CPU time.
+Use Flame Graphs when you:
+
+* Need to understand which Scylla code path/functions are using the most time. For instance, when you have latency issues.
+* Need to compare time spent in particular Scylla code paths/functions on different shards. For instance, when you have latency issues on one CPU but not on the other.
+
+Run a Flame Graph
+-----------------
+
+**Procedure**
+
+#. Install flamegraph and flamegraph-stackcollapse-perf
+
+ From DNF
+
+ .. code-block:: shell
+
+ dnf install flamegraph.noarch flamegraph-stackcollapse-perf.noarch
+
+ If the above packages are not available in you distribution's repositories, you can clone the FlameGraph git repository
+
+ .. code-block:: shell
+
+ git clone https://github.com/brendangregg/FlameGraph
+ cd FlameGraph
+
+#. Run the following perf commands, using :doc:`Map CPU to Scylla Shards </kb/map-cpu>` and :doc:`Using the perf utility with Scylla </kb/use-perf>` for reference.
+
+ .. code-block:: shell
+
+ sudo perf record --call-graph dwarf -C <CPU on which you are onrecording>
+ sudo perf script | stackcollapse-perf.pl | flamegraph.pl > some_name.svg
+
+#. The result is an .svg file that is not just a picture but a dynamic diagram where you can search, zoom in, and zoom out. In order to enjoy a Flame Graph properly with all of its features you can open it in a browser such as Chrome or Firefox.
+
+
+.. image:: flamegraph.svg
+
+Tips
+----
+
+* On the CPU you are recording, try to load Scylla to consume 100% of the CPU runtime. Otherwise you’ll see a lot of OS functions related to the idle time handling
+
+* Recording on all shards (e.g. using “perf record” -p parameter) may lead to confusing results recording the same symbol called from different threads (shards). This is not recommended.
+
+
+
+
+
diff --git a/docs/kb/flamegraph.svg b/docs/kb/flamegraph.svg
--- a/docs/kb/flamegraph.svg
+++ b/docs/kb/flamegraph.svg
null
diff --git a/docs/kb/gc-grace-seconds.rst b/docs/kb/gc-grace-seconds.rst
--- a/docs/kb/gc-grace-seconds.rst
+++ b/docs/kb/gc-grace-seconds.rst
@@ -0,0 +1,43 @@
+==========================================
+How to Change gc_grace_seconds for a Table
+==========================================
+
+.. your title should be something customers will search for.
+
+**Topic: subject**
+
+How to change (reduce) gc_grace_seconds parameter of the table
+
+**Audience: Scylla administrators**
+
+
+Issue
+-----
+
+When you want to change the ``gc_grace_seconds`` parameter value for a particular table you should readjust your repairs frequency to have at
+least one successful full repair for the table in question every (new) ``gc_grace_seconds`` window as discussed `here <https://university.scylladb.com/courses/scylla-operations/lessons/repair-tombstones-and-scylla-manager/topic/repair-tombstones-and-scylla-manager/>`_
+in order to avoid data resurrection.
+
+In addition, you should follow the procedure below in order to avoid data resurrection after the changing the ``gc_grace_seconds`` and before the next repair.
+
+
+Resolution
+----------
+#. Run a :doc:`full repair </operating-scylla/manager/2.1/repair>` for the table in question.
+#. Change the ``gc_grace_seconds`` value for the table using the :ref:`ALTER table <alter-table-statement>` command.
+#. Verify that the schema is in sync after the change by issuing :doc:`nodetool describecluster </operating-scylla/nodetool-commands/describecluster>` command from all nodes.
+ Verify that only a single schema version is reported. Read the :doc:`Schema Mismatch Troubleshooting Guide </troubleshooting/error-messages/schema-mismatch>` if it's not the case.
+#. Make sure that you run at least one :doc:`full repair </operating-scylla/manager/2.1/repair>` for the table in question during the ``gc_grace_seconds`` time window.
+ For example, if the ``gc_grace_seconds`` is set to 10 days, you should run a full repair on your tables every 8-9 days to make sure your tables are repaired before the ``gc_grace_seconds`` threshold is reached.
+
+
+Additional Notes
+----------------
+You can also avoid data resurrection (and hence the requirement of running the repair every gc_grace_seconds)
+if you make sure that tombstones are generated with operations that use Consistency Level: *ALL*
+
+The operations that generate tombstones are:
+
+* DELETE operations
+* TTLs
+* INSERT/UPDATE operations that overwrite the whole composite type value(s) like *map*, *list* or *UDT*.
diff --git a/docs/kb/gossip.rst b/docs/kb/gossip.rst
--- a/docs/kb/gossip.rst
+++ b/docs/kb/gossip.rst
@@ -0,0 +1,65 @@
+Gossip in Scylla
+================
+**Topic: Internals**
+
+**Audience: Devops professionals, architects**
+
+Scylla, like Apache Cassandra, uses a type of protocol called “gossip” to exchange metadata about the identities of nodes in a cluster and whether nodes are up or down. Of course, since there is no single point of failure there can be no single registry of node state, so nodes must share information among themselves.
+
+Gossip protocols are only required in distributed systems so are probably new to most administrators. `According to Wikipedia <https://en.wikipedia.org/wiki/Gossip_protocol>`_, the ideal gossip protocol has several qualities:
+
+* Gossip involves periodic, pairwise interactions between nodes
+* Information exchanged between nodes is of bounded size.
+* The state of at least one agent changes to reflect the state of the other.
+* Reliable communication is not assumed.
+* The frequency of the interactions is low compared to typical message latencies so that the protocol costs are negligible.
+* There is some form of randomness in the peer selection.
+* Due to the replication there is an implicit redundancy of the delivered information.
+
+Individual gossip interactions in Scylla, like Apache Cassandra, are relatively infrequent and simple.
+Each node, once per second, randomly selects 1 to 3 nodes to interact with.
+
+Each node runs the gossip protocol once per second, but the gossip runs are not synchronized across the cluster.
+
+One round = three messages
+--------------------------
+One round of gossip consists of three messages. (We’ll call the node initiating the round Node A, and the randomly selected node Node B).
+
+* Node A sends: gossip_digest_syn
+* Node B sends: gossip_digest_ack
+* Node A replies: gossip_digest_ack2
+
+While the names are borrowed from TCP, gossip does not require making a new TCP connection between nodes.
+
+What are nodes gossiping about?
+-------------------------------
+Nodes exchange a small amount of information about each other. The main two data structures are heart_beat_state and application_state.
+
+A heart_beat_state contains integers for generation and “version number”. The generation is a number that grows each time the node is started, and version number is an ever-increasing integer that covers the version of the application state. ApplicationState contains data on status of components within the node (such as load) and a version number. Each node maintains a map of node IP address and node gossip metadata for all nodes in the cluster including itself.
+
+A round of gossip is designed to minimize the amount of data sent, while resolving any conflicts between the node state data on the two gossiping nodes. In the gossip_digest_syn message, Node A sends a gossip digest: a list of all its known nodes, generations, and versions. Node B compares generation and version to its known nodes, and, in the gossip_digest_ack message, sends any of its own data that differ, along with its own digest. Finally, Node A replies with any state differences between its known state and Node B’s digest.
+
+Scylla gossip implementation
+----------------------------
+Scylla gossip messages run over the Scylla messaging_service, along with all other inter-node traffic including sending mutations, and streaming of data. Scylla’s messaging_service runs on the Seastar RPC service. Seastar is the scalable software framework for multicore systems that Scylla uses. If no TCP connection is up between a pair of nodes, messaging_service will create a new one. If it is up already, messaging service will use the existing one.
+
+Gossip on multicore
+-------------------
+Each Scylla node consists of several independent shards, one per core, which operate on a shared-nothing basis and communicate without locking. Internally, the gossip component, which runs on CPU 0 only, needs to have connections forwarded from other shards. The node state data, shared by gossip, is replicated to the other shards.
+
+The gossip protocol provides important advantages especially for large clusters. Compared to “flooding” information across nodes, it can synchronize data faster, and allow for fast recovery when a new node is down or a node is returned to service. Nodes only mark other nodes as down if an actual failure is detected, but gossip quickly shares the good news of a node coming back up.
+
+References
+----------
+`Cassandra Wiki: ArchitectureGossip <https://cwiki.apache.org/confluence/display/CASSANDRA2/ArchitectureGossip>`_
+
+`Apple Inc.: Cassandra Internals — Understanding Gossip <https://www.youtube.com/watch?v=FuP1Fvrv6ZQ&list=PLqcm6qE9lgKJkxYZUOIykswDndrOItnn2&index=49>`_
+
+`Using Gossip Protocols For Failure Detection, Monitoring, Messaging And Other Good Things, by Todd Hoff <http://highscalability.com/blog/2011/11/14/using-gossip-protocols-for-failure-detection-monitoring-mess.html>`_
+
+`Gossip protocol on Wikipedia <https://en.wikipedia.org/wiki/Gossip_protocol>`_
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/ics-incremental-compaction.png b/docs/kb/ics-incremental-compaction.png
--- a/docs/kb/ics-incremental-compaction.png
+++ b/docs/kb/ics-incremental-compaction.png
null
diff --git a/docs/kb/increase-permission-cache.rst b/docs/kb/increase-permission-cache.rst
--- a/docs/kb/increase-permission-cache.rst
+++ b/docs/kb/increase-permission-cache.rst
@@ -0,0 +1,43 @@
+====================================================
+Increase Permission Cache to Avoid Non-paged Queries
+====================================================
+
+**Topic: Mitigate non-paged queries coming from connection authentications**
+
+**Audience: Scylla administrators**
+
+
+
+Issue
+-----
+
+If you create lots of roles and give them lots of permissions your nodes might spike with non-paged queries.
+
+Root Cause
+----------
+
+``permissions_cache_max_entries`` is set to 1000 by default. This setting may not be high enough for bigger deployments with lots of tables, users, and roles with permissions.
+
+
+Solution
+--------
+
+Open the scylla.yaml configuration for editing and adjust the following parameters:
+``permissions_cache_max_entries`` - increase this value to suit your needs. See the example below.
+``permissions_update_interval_in_ms``
+``permissions_validity_in_ms``
+
+Note:: ``permissions_update_interval_in_ms`` and ``permissions_validity_in_ms`` can be set to also make the authentication records come from cache instead of lookups, which generate non-paged queries
+
+
+Example
+-------
+
+Considering with ``permissions_cache_max_entries`` there is no maximum value, it's just limited by your memory.
+The cache consumes memory as it caches all records from the list of users and their associated roles (similar to a cartesian product).
+
+Every user, role, and permissions(7 types) on a per table basis are cached.
+
+If for example, you have 1 user with 1 role and 1 table, the table will have 7 permission types and 7 entries 1 * 1 * 1 * 7 = 7.
+When expanded to 5 users, 5 roles, and 10 tables this will be 5 * 5 * 10 * 7 = 1750 entries, which is above the default cache value of 1000. The entries that go over the max value (750 entries) will be non-paged queries for every new connection from the client (and clients tend to reconnect often).
+In cases like this, you may want to consider trading your memory for not stressing the entire cluster with ``auth`` queries.
\ No newline at end of file
diff --git a/docs/kb/index.rst b/docs/kb/index.rst
--- a/docs/kb/index.rst
+++ b/docs/kb/index.rst
@@ -0,0 +1,82 @@
+Knowledge Base
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+ :glob:
+
+ /kb/*
+
+.. panel-box::
+ :title: Planning and Setup
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Seed Nodes </kb/seed-nodes>` - Introduction on the purpose and role of Seed Nodes in Scylla as well as configuration tips.
+ * :doc:`Compaction </kb/compaction>` - To free up disk space and speed up reads, Scylla must do compaction operations.
+ * :doc:`DPDK mode </kb/dpdk-hardware>` - Learn to select and configure networking for DPDK mode
+ * :doc:`POSIX networking for Scylla </kb/posix>` - Scylla's POSIX mode works on all physical and virtual network devices and is useful for development work.
+ * :doc:`System Limits </kb/system-limits>` - Outlines the system limits which should be set or removed
+ * :doc:`Run Scylla as a custom user:group </kb/custom-user>` - Configure the Scylla and supporting services to run as a custom user:group.
+ * :doc:`How to Set up a Swap Space Using a File </kb/set-up-swap>` - Outlines the steps you need to take to set up a swap space.
+
+
+.. panel-box::
+ :title: Scylla under the hood
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Gossip in Scylla </kb/gossip>` - Scylla, like Cassandra, uses a type of protocol called “gossip” to exchange metadata about the identities of nodes in a cluster. Here's how it works behind the scenes.
+ * :doc:`Scylla consistency quiz for administrators </kb/quiz-administrators>` - How much do you know about NoSQL, from the administrator point of view?
+ * :doc:`Scylla Memory Usage </kb/memory-usage>` - Short explanation how Scylla manages memory
+ * :doc:`Scylla Nodes are Unresponsive </kb/unresponsive-nodes>` - How to handle swap in Scylla
+ * :doc:`CQL Query Does Not Display Entire Result Set </kb/cqlsh-more>` - What to do when a CQL query doesn't display the entire result set.
+ * :doc:`Snapshots and Disk Utilization </kb/disk-utilization>` - How snapshots affect disk utilization
+ * :doc:`Scylla Snapshots </kb/snapshots>` - What Scylla snapshots are, what they are used for, and how they get created and removed.
+ * :doc:`How does Scylla LWT Differ from Apache Cassandra ? </kb/lwt-differences>` - How does Scylla's implementation of lightweight transactions differ from Apache Cassandra?
+ * :doc:`If a query does not reveal enough results </kb/cqlsh-results>`
+ * :doc:`How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds>` - How to change the ``gc_grace_seconds`` parameter and prevent data resurrection.
+ * :doc:`How to flush old tombstones from a table </kb/tombstones-flush>` - How to remove old tombstones from SSTables.
+ * :doc:`Increase Cache to Avoid Non-paged Queries </kb/increase-permission-cache>` - How to increase the ``permissions_cache_max_entries`` setting.
+ * :doc:`How to Safely Increase the Replication Factor </kb/rf-increase>`
+ * :doc:`Facts about TTL, Compaction, and gc_grace_seconds <ttl-facts>`
+
+ **Note**: The KB article for social readers has been *removed*. Instead, please look at lessons on `Scylla University <https://university.scylladb.com/>`_ or the `Care Pet example <https://care-pet.docs.scylladb.com/master/>`_
+
+
+.. panel-box::
+ :title: Configuring and Integrating Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`NTP configuration for Scylla </kb/ntp>` - Scylla depends on an accurate system clock. Learn to configure NTP for your data store and applications.
+ * :doc:`Scylla and Spark integration </kb/scylla-and-spark-integration>` - How to run an example Spark application that uses Scylla to store data?
+ * :doc:`Map CPUs to Scylla Shards </kb/map-cpu>` - Mapping between CPUs and Scylla shards
+ * :doc:`Recreate RAID devices </kb/raid-device>` - How to recreate your RAID devices without running scylla-setup
+ * :doc:`Configure Scylla Networking with Multiple NIC/IP Combinations </kb/yaml-address>` - examples for setting the different IP addresses in scylla.yaml
+ * :doc:`Kafka Sink Connector Quickstart </using-scylla/integrations/kafka-connector>`
+ * :doc:`Kafka Sink Connector Configuration </using-scylla/integrations/sink-config>`
+
+
+.. panel-box::
+ :title: Analyzing Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Using the perf utility with Scylla </kb/use-perf>` - Using the perf utility to analyze Scylla
+ * :doc:`Debug your database with Flame Graphs </kb/flamegraph>` - How to setup and run a Flame Graph
+ * :doc:`Decoding Stack Traces </kb/decode-stack-trace>` - How to decode stack traces in Scylla Logs
+ * :doc:`Counting all rows in a table </kb/count-all-rows>` - Why counting all rows in a table often leads to a timeout
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/kb/lwt-differences.rst b/docs/kb/lwt-differences.rst
--- a/docs/kb/lwt-differences.rst
+++ b/docs/kb/lwt-differences.rst
@@ -0,0 +1,16 @@
+==================================================
+How does Scylla LWT Differ from Apache Cassandra ?
+==================================================
+
+Scylla is making an effort to be compatible with Cassandra, down to the level of limitations of the implementation.
+How is it different?
+
+* Scylla most commonly uses fewer rounds than Cassandra to complete a lightweight transaction. While Cassandra issues a separate read query to fetch the old record, scylla piggybacks the read result on the response to the prepare round.
+* Scylla will automatically use synchronous commit log write mode for all lightweight transaction writes. Before a lightweight transaction completes, scylla will ensure that the data in it has hit the device. This is done in all commitlog_sync modes.
+* Conditional statements return a result set, and unlike Cassandra, Scylla result set metadata doesn’t change from execution to execution: Scylla always returns the old version of the row, regardless of whether the condition is true or not. This ensures conditional statements work well with prepared statements.
+* For batch statement, the returned result set contains an old row for every conditional statement in the batch, in statement order. Cassandra returns results in clustering key order.
+* Unlike Cassandra, Scylla uses per-core data partitioning, so the RPC that is done to perform a transaction talks directly to the right core on a peer replica, avoiding the concurrency overhead. This is, of course, true, if Scylla’s own shard-aware driver is used - otherwise we add an extra hop to the right core at the coordinator node.
+* Scylla does not store hints for lightweight transaction writes, since this is redundant as all such writes are already present in system.paxos table.
+
+
+More on :doc:`Lightweight Transactions (LWT) </using-scylla/lwt>`
diff --git a/docs/kb/map-cpu.rst b/docs/kb/map-cpu.rst
--- a/docs/kb/map-cpu.rst
+++ b/docs/kb/map-cpu.rst
@@ -0,0 +1,42 @@
+==========================
+Map CPUs to Scylla Shards
+==========================
+
+Due to its thread-per-core architecture, many things within Scylla can be better understood when you look at it on a per-CPU basis. There are Linux tools such as ``top`` and ``perf`` that can give information about what is happening within a CPU, given a CPU number.
+
+A common mistake users make is to assume that there is a direct and predictable relationship between the Scylla Shard ID and the CPU ID, which is not true.
+
+Starting in version 3.0, Scylla ships with a script to let users know about the mapping between CPUs and Scylla Shards. For users of older versions, a copy of the script can be downloaded from the `Seastar git tree <https://raw.githubusercontent.com/scylladb/seastar/master/scripts/seastar-cpu-map.sh>`_.
+
+Examples of usage
+------------------
+
+To list the mapping of a specific shard:
+
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla -s 0
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+
+To list the mapping of all shards:
+
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+ shard: 1, cpu: 2
+ shard: 3, cpu: 4
+ shard: 2, cpu: 3
+
diff --git a/docs/kb/memory-usage.rst b/docs/kb/memory-usage.rst
--- a/docs/kb/memory-usage.rst
+++ b/docs/kb/memory-usage.rst
@@ -0,0 +1,30 @@
+Scylla Memory Usage
+===================
+
+Scylla memory usage might be larger than the data set used.
+
+For example:
+
+``The data size is 19GB, but Scylla uses 220G memory.``
+
+
+Scylla uses available memory to cache your data. Scylla knows how to dynamically manage memory for optimal performance, for example, if many clients connect to Scylla, it will evict some data from the cache to make room for these connections, when the connection count drops again, this memory is returned to the cache.
+
+To limit the memory usage you can start scylla with ``--memory`` parameter.
+Alternatively, you can specify the amount of memory ScyllaDB should leave to the OS with ``--reserve-memory`` parameter. Keep in mind that the amount of memory left to the operating system needs to suffice external scylla modules, such as ``scylla-jmx``, which runs on top of JVM.
+
+On Ubuntu, edit the ``/etc/default/scylla-server``.
+
+On Red Hat / CentOS, edit the ``/etc/sysconfig/scylla-server``.
+
+
+
+For example:
+
+.. code-block:: yaml
+
+ SCYLLA_ARGS="--log-to-syslog 1 --log-to-stdout 0 --default-log-level info --collectd-address=127.0.0.1:25826 --collectd=1 --collectd-poll-period 3000 --network-stack posix --memory 2G --reserve-memory 2G
+
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/ntp.rst b/docs/kb/ntp.rst
--- a/docs/kb/ntp.rst
+++ b/docs/kb/ntp.rst
@@ -0,0 +1,148 @@
+NTP Configuration for Scylla
+============================
+**Topic: System administration**
+
+**Learn: How to configure time synchronization for Scylla**
+
+**Audience: Scylla and Apache Cassandra administrators**
+
+Apache Cassandra and Scylla depend on an accurate system clock. Kyle Kingsbury,
+author of the ``jepsen`` distributed systems testing tool,
+`writes <https://aphyr.com/posts/299-the-trouble-with-timestamps>`_,
+
+ Apache Cassandra uses wall-clock timestamps provided by the server, or
+ optionally by the client, to order writes. It makes several
+ guarantees about the monotonicity of writes and reads given
+ timestamps. For instance, Cassandra guarantees most of the time that
+ if you write successfully to a quorum of nodes, any subsequent read
+ from a quorum of nodes will see that write or one with a greater
+ timestamp.
+
+So servers need to keep their time in sync. Not a hard problem, since we
+all have NTP on our Linux systems, right? Not quite. The way that NTP
+ships out of the box is fine for a stand-alone server, but can be a
+problem for a distributed data store.
+
+You did WHAT in the Pool?
+-------------------------
+
+The default NTP configuration that comes with a typical Linux system
+uses “NTP pools”, lists of publicly available time servers contributed
+by public-minded Internet timekeeping system administrators. The pools
+are a valuable service, but in order to spare the NTP traffic load on
+any given server, they’re managed with DNS round robin. One client that
+tries to resolve the hostname ``0.pool.ntp.org`` will get a different
+result from another client.
+
+As Viliam Holub points out in a two-part series -- `part
+1 <https://blog.logentries.com/2014/03/synchronizing-clocks-in-a-cassandra-cluster-pt-1-the-problem/>`__,
+`part
+2 <https://blog.logentries.com/2014/03/synchronizing-clocks-in-a-cassandra-cluster-pt-2-solutions/>`__
+-- if Apache Cassandra nodes in a cluster are independently obtaining their
+time from random pool servers out on the Internet, the chances that two
+nodes can have widely (by NTP standards) differing time is high. For
+example, if a cluster has 10 nodes, 50% of the time some pair of nodes
+will have time that differs by more than 10.9ms. The problem only grows
+as more nodes are added.
+
+The solution is to be able to take that ntp.conf file that came with
+your Linux distribution, and take the default “pool” servers out and put
+your data center’s own NTP servers in.
+
+Instead of lines that looks something like:
+
+::
+
+ server 0.fedora.pool.ntp.org iburst
+ server 1.fedora.pool.ntp.org iburst
+
+Or
+
+::
+
+ server 0.debian.pool.ntp.org iburst
+ server 1.debian.pool.ntp.org iburst
+
+use your own servers. So ntp.conf will have “server” lines pointing to
+your own NTP servers, and look more like:
+
+::
+
+ # begin ntp.conf
+
+ # Store clock drift -- see ntp.conf(5)
+ driftfile /var/lib/ntp/drift
+
+ # Restrict all access by default
+ restrict default nomodify notrap nopeer noquery
+
+ # Allow localhost access and LAN management
+ restrict 127.0.0.1
+ restrict ::1
+ restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap
+
+ # Use our company’s NTP servers only
+ server 0.ntp.example.com iburst
+ server 1.ntp.example.com iburst
+ server 2.ntp.example.com iburst
+
+ # End ntp.conf
+
+The same ntp.conf can be deployed to all the servers in your data
+center. Not just Apache Cassandra nodes, but the application servers that use
+them. It’s much more important for the time to be in sync throughout the
+cluster than for any node to match some random machine out on the
+Internet. It’s also helpful to keep the data store time the same as the
+application server’s time, for ease in troubleshooting and matching up
+log entries.
+
+Dedicated NTP appliances are available, and might be a good choice for
+large sites. Otherwise, any standard Linux system should make a good NTP
+server.
+
+On the NTP servers, you can go ahead and use the “pool.ntp.org” server
+lines that shipped with your Linux distribution if you don’t have a
+known good time server. But a good hosting provider or business-class
+ISP probably has NTP servers that are close to you on the network, and
+that would be better choices to replace the pool entries.
+
+Your NTP servers should peer with each other:
+
+::
+
+ peer 0.ntp.example.com prefer
+ peer 1.ntp.example.com
+ peer 2.ntp.example.com
+
+Almost done.
+
+Pass the Fudge?
+---------------
+
+What happens when the network goes down? In most cases, NTP should just
+work. Your NTP servers will establish a new consensus time among
+themselves. Old-school NTP documentation had “fudge” lines to let the
+NTP server rely on the local system clock if the network connection
+failed. On modern versions of NTP, the “fudge” functionality has been
+replaced with `Orphan
+mode <http://support.ntp.org/bin/view/Support/OrphanMode>`__.
+
+Add an “orphan” line to ntp.conf on each NTP server:
+
+::
+
+ tos orphan 9
+
+And the NTP servers will do the right thing and stay synchronized among
+themselves if there’s a problem reaching the servers on the outside.
+
+That’s all it takes. One relatively simple system administration project
+can save a bunch of troubleshooting grief later on. Once your NTP
+servers are working, have a look at the `instructions for joining the
+NTP pool <http://www.pool.ntp.org/join.html>`__ yourself, so that you
+can help share the correct time with others
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/perf-top.png b/docs/kb/perf-top.png
--- a/docs/kb/perf-top.png
+++ b/docs/kb/perf-top.png
null
diff --git a/docs/kb/posix.rst b/docs/kb/posix.rst
--- a/docs/kb/posix.rst
+++ b/docs/kb/posix.rst
@@ -0,0 +1,55 @@
+POSIX networking for Scylla
+===========================
+**Topic: Planning and setup**
+
+**Learn: How to configure POSIX networking for Scylla**
+
+**Audience: Developers, devops, integration testers**
+
+The Seastar framework used in Scylla can support two networking modes.
+For high-performance production workloads, use the Data Plane
+Development Kit (DPDK) for maximum performance on specific modern
+network hardware.
+
+For ease of development, you can also use POSIX mode, which works on all
+physical and virtual network devices supported by your operating system.
+
+Kernel Configuration
+--------------------
+
+The Linux “transparent hugepages” feature is recommended, but not
+required, in POSIX mode to minimize overhead on memory allocations. The
+value of ``/sys/kernel/mm/transparent_hugepage/enabled`` should be
+``always`` or ``madvise``. See your Linux distribution's documentation
+for instructions on how to enable transparent hugepages.
+
+Firewall Configuration
+----------------------
+
+For a single node, the firewall will need to be set up to allow TCP on
+the following :ref:`ports <cqlsh-networking>`.
+
+Scylla Configuration
+--------------------
+
+POSIX mode is the default, in ``/etc/sysconfig/scylla-server``. Check
+that ``NETWORK_MODE`` is set to ``posix``.
+
+::
+
+ # choose following mode: virtio, dpdk, posix
+ NETWORK_MODE=posix.
+
+The ``ETHDRV`` option is ignored in POSIX mode.
+
+More Information
+----------------
+
+`Cassandra: configuring firewall port
+access <http://docs.datastax.com/en//cassandra/2.0/cassandra/security/secureFireWall_r.html>`__
+
+`How to use, monitor, and disable transparent hugepages in Red Hat
+Enterprise Linux 6 <https://access.redhat.com/solutions/46111>`__
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/quiz-administrators.rst b/docs/kb/quiz-administrators.rst
--- a/docs/kb/quiz-administrators.rst
+++ b/docs/kb/quiz-administrators.rst
@@ -0,0 +1,34 @@
+Scylla consistency quiz for administrators
+==========================================
+**Topic: Architecture and development**
+
+**Learn: Understanding consistency in Scylla: a quiz**
+
+**Audience: Scylla administrators**
+
+Q: When you run ``nodetool decommission`` to remove a node…
+
+1. Will the token range the node had be relocated to other nodes?
+ What about vnodes?
+
+2. When and how will we know the “decommission” operation is finished?
+
+A1. Yes. The node enters the state “STATE\_LEAVING” while streaming its
+data to other nodes. Then it is in “STATE\_LEFT” when the data has been
+streamed.
+
+A2. Use ``nodetool netstats`` to check the state of a node.
+
+Q: Let's say I have a 16 node cluster using Network Topology Strategy
+across 2 data centers. The replication factor is TWO in each datacenter
+(DC1: 2, DC2: 2). If I write using a LOCAL\_QUORUM, I will write the
+data to 4 nodes (2 in each data center) but when will the
+acknowledgement happen?
+
+
+A: The acknowledgment will be sent to the user when two **local** replicas respond.
+In this case, floor(local_RF/2 +1) = 2 , so LOCAL\_QUORUM is equal to RF per DC, which is why RF of 3 is usually better.
+
+
+`Knowledge Base
+</kb/>`_
diff --git a/docs/kb/raid-device.rst b/docs/kb/raid-device.rst
--- a/docs/kb/raid-device.rst
+++ b/docs/kb/raid-device.rst
@@ -0,0 +1,14 @@
+=====================
+Recreate RAID devices
+=====================
+
+Scylla creates a RAID device on all storage devices assigned to it as part of Scylla setup. However, there are situations in which we want to redo just this step, without invoking the entire setup phase again. One example of such a situation is when Scylla is used in Clouds with ephemeral storage. After a hard stop, the storage devices will be reset and the previous setup will be destroyed.
+To recreate your RAID devices, run this script:
+
+.. code-block:: shell
+
+ scylla_raid_setup --raiddev /dev/md0 --disks <comma-separated list of disks>
+
+After this step the storage will be mounted, formatted, and /var/lib/scylla created.
+
+
diff --git a/docs/kb/rf-increase.rst b/docs/kb/rf-increase.rst
--- a/docs/kb/rf-increase.rst
+++ b/docs/kb/rf-increase.rst
@@ -0,0 +1,50 @@
+=======================================================
+How to Safely Increase the Replication Factor
+=======================================================
+
+
+**Topic: What can happen when you increase RF**
+
+
+**Audience: Scylla administrators**
+
+
+Issue
+-----
+
+When a Replication Factor (RF) is increased, using the :ref:`ALTER KEYSPACE <alter-keyspace-statement>` command, the data consistency is effectively dropped
+by the difference of the RF_new value and the RF_old value for all pre-existing data.
+Consistency will only be restored after running a repair.
+
+Resolution
+----------
+
+When one increases an RF, one should consider that the pre-existing data will **not be streamed** to new replicas (a common misconception).
+
+As a result, in order to make sure that you can keep on reading the old data with the same level of consistency, increase the read Consistency Level (CL) according to the following formula:
+
+``CL_new = CL_old + RF_new - RF_old``
+
+After you run a repair, you can decrease the CL. If RF has only been changed in a particular Data Center (DC) only the nodes in that DC have to be repaired.
+
+Example
+=======
+
+In this example your five node cluster RF is 3 and your CL is TWO. You want to increase your RF from 3 to 5.
+
+#. Increase the read CL by a RF_new - RF_old value.
+ Following the example the RF_new is 5 and the RF_old is 3 so, 5-3 =2. You need to increase the CL by 2.
+ As the CL is currently TWO, increasing it more would be QUORUM, but QUORUM would not be high enough. For now, increase it to ALL.
+#. Change the RF to RF_new. In this example, you would increase the RF to 5.
+#. Repair all tables of the corresponding keyspace. If RF has only been changed in a particular Data Center (DC), only the DC nodes have to be repaired.
+#. Restore the reads CL to the originally intended value. For this example, QUORUM.
+
+
+If you do not follow the procedure above you may start reading stale or null data after increasing the RF.
+
+More Information
+----------------
+
+* :doc:`Fault Tolerance </architecture/architecture-fault-tolerance/>`
+* :ref:`Set the RF (first time) <create-keyspace-statement>`
+* :ref:`Change the RF (increase or decrease) <alter-keyspace-statement>`
diff --git a/docs/kb/scylla-and-spark-integration.rst b/docs/kb/scylla-and-spark-integration.rst
--- a/docs/kb/scylla-and-spark-integration.rst
+++ b/docs/kb/scylla-and-spark-integration.rst
@@ -0,0 +1,359 @@
+Scylla and Spark integration
+============================
+
+
+Simple Scylla-Spark integration example
+---------------------------------------
+
+This is an example of how to create a very simple Spark application that
+uses Scylla to store its data. The application is going to read people's
+names and ages from one table and write the names of the adults to
+another one. It also will show the number of adults and all people in
+the database.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- Scylla
+- sbt
+
+Prepare Scylla
+~~~~~~~~~~~~~~
+
+Firstly, we need to create keyspace and tables in which data processed
+by the example application will be stored.
+
+Launch Scylla and connect to it using cqlsh. The following commands will
+create a new keyspace for our tests and make it the current one.
+
+::
+
+ CREATE KEYSPACE spark_example WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1};
+ USE spark_example;
+
+Then, tables both for input and output data need to be created:
+
+::
+
+ CREATE TABLE persons (name TEXT PRIMARY KEY, age INT);
+ CREATE TABLE adults (name TEXT PRIMARY KEY);
+
+Lastly, the database needs to contain some input data for our
+application to process:
+
+::
+
+ INSERT INTO persons (name, age) VALUES ('Anne', 34);
+ INSERT INTO persons (name, age) VALUES ('John', 47);
+ INSERT INTO persons (name, age) VALUES ('Elisabeth', 89);
+ INSERT INTO persons (name, age) VALUES ('George', 52);
+ INSERT INTO persons (name, age) VALUES ('Amy', 17);
+ INSERT INTO persons (name, age) VALUES ('Jack', 16);
+ INSERT INTO persons (name, age) VALUES ('Treebeard', 36421);
+
+Prepare the application
+~~~~~~~~~~~~~~~~~~~~~~~
+
+With a database containing all the necessary tables and data, it is now
+time to write our example application. Create a directory
+``scylla-spark-example``, which will contain all source code and build
+configuration.
+
+First, very important file is ``build.sbt``, which should be created in
+the project main directory. It contains all the application metadata,
+including name, version, and dependencies.
+
+::
+
+ name := "scylla-spark-example-simple"
+ version := "1.0"
+ scalaVersion := "2.10.5"
+
+ libraryDependencies ++= Seq(
+ "com.datastax.spark" %% "spark-cassandra-connector" % "1.5.0-M1",
+ "org.apache.spark" %% "spark-catalyst" % "1.5.0" % "provided"
+ )
+
+Then, we need to enable ``sbt-assembly`` plugin. Create directory
+``project`` and create file ``plugins.sbt`` with the following content:
+
+::
+
+ addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.0")
+
+The steps above should cover all build configuration, what is left is
+the actual logic of the application. Create file
+``src/main/scala/ScyllaSparkExampleSimple.scala``:
+
+.. code:: scala
+
+ import org.apache.spark.{SparkContext,SparkConf}
+ import com.datastax.spark.connector._
+
+ object ScyllaSparkExampleSimple {
+ def main(args: Array[String]): Unit = {
+ val sc = new SparkContext(new SparkConf())
+
+ val persons = sc.cassandraTable("spark_example", "persons")
+
+ val adults = persons.filter(_.getInt("age") >= 18).map(n => Tuple1(n.getString("name")))
+ adults.saveToCassandra("spark_example", "adults")
+
+ val out = s"Adults: %d\nTotal: %d\n".format(adults.count(), persons.count())
+ println(out)
+ }
+ }
+
+Since we don't want to hardcode in our application any information about
+Scylla or Spark we will also need an additional configuration file
+``spark-scylla.conf``.
+
+::
+
+ spark.master local
+ spark.cassandra.connection.host 127.0.0.1
+
+Now it is time to build the application and create a self-containing jar
+file that we will be able to send to Spark. To do that, execute the command:
+
+::
+
+ sbt assembly
+
+It will download all necessary dependencies, build our example, and
+create an output jar file in
+``target/scala-2.10/scylla-spark-example-simple-assembly-1.0.jar``.
+
+Download and run Spark
+~~~~~~~~~~~~~~~~~~~~~~
+
+The next step is to get Spark running. Pre-built binaries can be
+downloaded from `this <http://spark.apache.org/downloads.html>`__
+website. Make sure to choose release 1.5.0. Since we are going to use it
+with Scylla Hadoop version doesn't matter.
+
+Once the download has finished, unpack the archive and in its root
+directory, execute the following command to start Spark Master:
+
+::
+
+ ./sbin/start-master.sh -h localhost
+
+Spark Web UI should now be available at http://localhost:8080. The Spark
+URL used to connect its workers is ``spark://localhost:7077``.
+
+With the master running, the only thing left to have minimal Spark
+deployment is to start a worker. This can be done with the following
+command:
+
+::
+
+ ./sbin/start-slave.sh spark://localhost:7077
+
+Run application
+~~~~~~~~~~~~~~~
+
+The application is built, Spark is up, and Scylla has all the necessary
+tables created and contains the input data for our example. This means
+that we are ready to run the application. Make sure that Scylla is
+running and execute (still in the Spark directory) the following
+command):
+
+::
+
+ ./bin/spark-submit --properties-file /path/to/scylla-spark-example/spark-scylla.conf \
+ --class ScyllaSparkExampleSimple /path/to/scylla-spark-example/target/scala-2.10/scylla-spark-example-simple-assembly-1.0.jar
+
+``spark-submit`` will output some logs and debug information, but among
+them, there should be a message from the application:
+
+::
+
+ Adults: 5
+ Total: 7
+
+You can also connect to Scylla with cqlsh, and using the following query,
+see the results of our example in the database.
+
+::
+
+ SELECT * FROM spark_example.adults;
+
+Expected output:
+
+::
+
+ name
+ -----------
+ Treebeard
+ Elisabeth
+ George
+ John
+ Anne
+
+Based on
+http://www.planetcassandra.org/getting-started-with-apache-spark-and-cassandra/
+and http://koeninger.github.io/spark-cassandra-example/#1.
+
+RoadTrip example
+----------------
+
+This is a short guide explaining how to run a Spark example application
+available `here <https://github.com/jsebrien/spark-tests>`__ with
+Scylla.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- Scylla
+- Maven
+- Git
+
+Get the source code
+~~~~~~~~~~~~~~~~~~~
+
+You can get the source code of this example by cloning the following
+repository:
+
+::
+
+ https://github.com/jsebrien/spark-tests
+
+Disable Apache Cassandra
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+spark-tests are configured to launch Cassandra, which is not what we want
+to achieve here. The following patch disables Cassandra. It can be
+applied, for example, using ``git apply --ignore-whitespace -``.
+
+.. code:: diff
+
+ diff --git a/src/main/java/blog/hashmade/spark/util/CassandraUtil.java b/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ index 37bbc2e..bfe5517 100644
+ --- a/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ +++ b/src/main/java/blog/hashmade/spark/util/CassandraUtil.java
+ @@ -14,7 +14,7 @@ public final class CassandraUtil {
+ }
+
+ static Session startCassandra() throws Exception {
+ - EmbeddedCassandraServerHelper.startEmbeddedCassandra();
+ + //EmbeddedCassandraServerHelper.startEmbeddedCassandra();
+ Thread.sleep(EMBEDDED_CASSANDRA_SERVER_WAITING_TIME);
+ Cluster cluster = new Cluster.Builder().addContactPoints("localhost")
+ .withPort(9142).build();
+
+Update connector
+~~~~~~~~~~~~~~~~
+
+spark-tests use Spark Cassandra Connector in version 1.1.0 which is too
+old for our purposes. Before 1.3.0 the connector used to use Thrift as
+well CQL and that won't work with Scylla. Updating the example isn't
+very complicated and can be accomplished by applying the following
+patch:
+
+.. code:: diff
+
+ diff --git a/pom.xml b/pom.xml
+ index 673e22b..1245ffc 100644
+ --- a/pom.xml
+ +++ b/pom.xml
+ @@ -142,7 +142,7 @@
+ <dependency>
+ <groupId>org.apache.spark</groupId>
+ <artifactId>spark-core_2.10</artifactId>
+ - <version>1.1.0</version>
+ + <version>1.3.0</version>
+ <exclusions>
+ <exclusion>
+ <groupId>com.google.guava</groupId>
+ @@ -157,7 +157,7 @@
+ <dependency>
+ <groupId>org.apache.spark</groupId>
+ <artifactId>spark-streaming_2.10</artifactId>
+ - <version>1.1.0</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.cassandraunit</groupId>
+ @@ -173,18 +173,18 @@
+ <dependency>
+ <groupId>com.datastax.cassandra</groupId>
+ <artifactId>cassandra-driver-core</artifactId>
+ - <version>2.1.2</version>
+ + <version>2.1.7.1</version>
+ </dependency>
+ <!-- Datastax -->
+ <dependency>
+ <groupId>com.datastax.spark</groupId>
+ <artifactId>spark-cassandra-connector_2.10</artifactId>
+ - <version>1.1.0-beta2</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>com.datastax.spark</groupId>
+ <artifactId>spark-cassandra-connector-java_2.10</artifactId>
+ - <version>1.1.0-beta2</version>
+ + <version>1.3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>net.sf.supercsv</groupId>
+ diff --git a/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java b/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ index 1027e42..190eb3d 100644
+ --- a/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ +++ b/src/main/java/blog/hashmade/spark/DatastaxSparkTest.java
+ @@ -43,8 +43,7 @@ public class DatastaxSparkTest {
+ .setAppName("DatastaxTests")
+ .set("spark.executor.memory", "1g")
+ .set("spark.cassandra.connection.host", "localhost")
+ - .set("spark.cassandra.connection.native.port", "9142")
+ - .set("spark.cassandra.connection.rpc.port", "9171");
+ + .set("spark.cassandra.connection.port", "9142");
+ SparkContext ctx = new SparkContext(conf);
+ SparkContextJavaFunctions functions = CassandraJavaUtil.javaFunctions(ctx);
+ CassandraJavaRDD<CassandraRow> rdd = functions.cassandraTable("roadtrips", "roadtrip");
+
+Build the example
+~~~~~~~~~~~~~~~~~
+
+The example can be built with Maven:
+
+::
+
+ mvn compile
+
+Start Scylla
+~~~~~~~~~~~~
+
+The application we are trying to run will try to connect with Scylla
+using custom port 9142. That's why when starting Scylla, an additional
+flag is needed to make sure that's the port it listens on
+(alternatively, you can change all occurrences of 9142 to 9042 in the
+example source code).
+
+::
+
+ scylla --native-transport-port=9142
+
+Run the application
+~~~~~~~~~~~~~~~~~~~
+
+With the example compiled and Scylla running all that is left to be done
+is to actually run the application:
+
+::
+
+ mvn exec:java
+
+Scylla limitations
+------------------
+
+- Scylla needs Spark Cassandra Connector 1.3.0 or later.
+- Scylla doesn't populate ``system.size_estimates``, and therefore the
+ connector won't be able to perform automatic split sizing optimally.
+
+For more compatibility information check `Scylla status <http://www.scylladb.com/technology/status/>`_
+
+`Knowledge Base
+</kb/>`_
+
+.. include:: /rst_include/apache-copyrights.rst
diff --git a/docs/kb/scylla-limits-systemd.rst b/docs/kb/scylla-limits-systemd.rst
--- a/docs/kb/scylla-limits-systemd.rst
+++ b/docs/kb/scylla-limits-systemd.rst
@@ -0,0 +1,94 @@
+============================================
+Increase Scylla resource limits over systemd
+============================================
+
+**Topic: Increasing resource limits when Scylla runs and is managed via systemd**
+
+**Audience: Scylla administrators**
+
+
+
+Issue
+-----
+
+Updates to ``/etc/security/limits.d/scylla.conf`` do not have any effect. After a cluster rolling restart is completed, the Scylla limits listed under ``/proc/<PID>/limits`` are still the same or lower than what has been configured.
+
+Root Cause
+----------
+
+When running under systemd, Scylla enforces the **LimitNOFILE** and **LimitNPROC** values under ``/lib/systemd/system/scylla-server.service``, where:
+
+**LimitNOFILE** - Maximum number of file descriptors allowed to be opened simultaneously (defaults to 800000)
+
+**LimitNPROC** - Maximum number of processes allowed to run in parallel (defaults to 8096)
+
+Even though Scylla's provided defaults are suitable for most workloads, there may be situations on which these values may need to be overriden.
+
+Before you start
+----------------
+
+The Linux kernel imposes an upper limit on the maximum number of file-handles that a process may allocate, which takes precedence over systemd. Such limit may be persistently increased by tuning the ``fs.nr_open`` parameter in the ``/etc/sysctl.conf`` file.
+
+The ``fs.nr_open`` parameter default value is 1048576 (1024*1024) and it must be increased whenever it is required to overcome such limit.
+
+As a rule of thumb, always ensure that the value of ``fs.nr_open`` is **equal or greater than** the maximum number of file-handles that Scylla may be able to consume.
+
+1. To check the value of ``fs.nr_open`` run:
+
+.. code-block:: shell
+
+ sysctl fs.nr_open
+ fs.nr_open = 1048576
+
+2. Edit the file ``/etc/sysctl.conf`` as root, and increase the value of ``fs.nr_open``:
+
+.. code-block:: shell
+
+ sudo vi /etc/sysctl.conf
+ fs.nr_open=5000000
+
+3. Save the changes and apply the new setting to the running configuration:
+
+.. code-block:: shell
+
+ sudo sysctl -p
+
+
+
+Solution
+--------
+
+1. To override Scylla limits on systemd, run:
+
+.. code-block:: shell
+
+ sudo systemctl edit scylla-server.service
+
+2. Within the opened text editor, add the following lines and adjust the parameters as needed, e.g.:
+
+**Warning**: Avoid setting the value of such fields to `Infinity` as this can lead to unpredictable behaviors. When adjusting the value of **LimitNOFILE** always set it to a value which is **equal or lower than** the value of ``fs.nr_open``
+
+.. code-block:: shell
+
+ [Service]
+ LimitNOFILE=5000000
+
+3. Restart Scylla:
+
+.. code-block:: shell
+
+ sudo systemctl restart scylla-server.service
+
+This will create a configuration file named ``override.conf`` under the ``/etc/systemd/system/scylla-server.service.d`` folder. Whenever editing this file by hand manually, remember to run ``sudo systemctl daemon-reload`` before restarting Scylla, so that systemd reloads the changes.
+
+4. To check the updated limits allowed by the Scylla process run:
+
+.. code-block:: shell
+
+ cat /proc/$(pidof scylla)/limits
+
+References
+----------
+
+* `The Linux Kernel Documentation for /proc/sys/fs/*` <https://www.kernel.org/doc/Documentation/sysctl/fs.txt>
+* `systemd.exec(5) manpage`
diff --git a/docs/kb/seed-nodes.rst b/docs/kb/seed-nodes.rst
--- a/docs/kb/seed-nodes.rst
+++ b/docs/kb/seed-nodes.rst
@@ -0,0 +1,48 @@
+=================
+Scylla Seed Nodes
+=================
+
+**Topic: Scylla Seed Nodes Overview**
+
+**Learn: What a seed node is, and how they should be used in a Scylla Cluster**
+
+**Audience: Scylla Administrators**
+
+
+What is the Function of a Seed Node in Scylla?
+----------------------------------------------
+
+.. note::
+ Seed nodes function was changed in Scylla Open Source 4.3 and Scylla Enterprise 2021.1; if you are running an older version, see :ref:`Older Version Of Scylla <seeds-older-versions>`.
+
+A Scylla seed node is a node specified with the ``seeds`` configuration parameter in ``scylla.yaml``. It is used by new node joining as the first contact point.
+It allows nodes to discover the cluster ring topology on startup (when joining the cluster). This means that any time a node is joining the cluster, it needs to learn the cluster ring topology, meaning:
+
+- What are the IPs of the nodes in the cluster are
+- Which token ranges are available
+- Which nodes will own which tokens when a new node joins the cluster
+
+**Once the nodes have joined the clutser, seed node has no function.**
+
+The first node in a new cluster needs to be a seed node.
+
+.. _seeds-older-versions:
+
+Older Version Of Scylla
+----------------------------
+
+In Scylla releases older than Scylla Open Source 4.3 and Scylla Enterprise 2021.1, seed node has one more function: it assists with :doc:`gossip </kb/gossip>` convergence.
+Gossiping with other nodes ensures that any update to the cluster is propagated across the cluster. This includes detecting and alerting whenever a node goes down, comes back, or is removed from the cluster.
+
+This functions was removed, as described in `Seedless NoSQL: Getting Rid of Seed Nodes in ScyllaDB <https://www.scylladb.com/2020/09/22/seedless-nosql-getting-rid-of-seed-nodes-in-scylla/>`_.
+
+If you run an older Scylla release, we recommend upgrading to version 4.3 (Scylla Open Source) or 2021.1 (Scylla Enterprise) or later. If you choose to run an older version, it is good practice to follow these guidelines:
+
+* The first node in a new cluster needs to be a seed node.
+* Ensure that all nodes in the cluster have the same seed nodes listed in each node's scylla.yaml.
+* To maintain resiliency of the cluster, it is recommended to have more than one seed node in the cluster.
+* If you have more than one seed in a DC with multiple racks (or availability zones), make sure to put your seeds in different racks.
+* You must have at least one node that is not a seed node. You cannot create a cluster where all nodes are seed nodes.
+* You should have more than one seed node.
+
+
diff --git a/docs/kb/set-up-swap.rst b/docs/kb/set-up-swap.rst
--- a/docs/kb/set-up-swap.rst
+++ b/docs/kb/set-up-swap.rst
@@ -0,0 +1,120 @@
+===========================
+How to Set up a Swap Space
+===========================
+
+.. note:: It is recommended to run the ``scylla_setup`` script to setup your swap space. ``scylla_setup`` runs a script called ``scylla_swap_setup``.
+ You can also run the script using the `Set Up Swap Space with a Script`_ procedure below. If this doesn't work use the procedure below to `Set Up Swap Space with a File`_.
+
+Set Up Swap Space with a Script
+-------------------------------
+
+The help for the script can be accessed by ``scylla_swap_setup --help``.
+
+.. code-block:: shell
+
+ scylla_swap_setup --help
+ usage: scylla_swap_setup [-h] [--swap-directory SWAP_DIRECTORY] [--swap-size SWAP_SIZE]
+
+ Configure swap for Scylla.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --swap-directory SWAP_DIRECTORY
+ specify swapfile directory
+ --swap-size SWAP_SIZE
+ specify swapfile size in GB
+
+
+**Procedure**
+
+#. Run the script setup command in a terminal specifying the target directory and size.
+
+.. code-block:: shell
+
+ sudo scylla_swap_setup --swap-directory /tmp/swp --swap-size SWAP_SIZE 500
+
+
+Set Up Swap Space with a File
+-----------------------------
+
+Use this procedure if the `Set Up Swap Space with a Script`_ procedure did not give you the desired results.
+
+This tutorial is suitable for any Linux distribution.
+
+This procedure adds 6GB of swap to your server. If you want to add a different amount, replace ``6G`` with the size you require.
+
+Keep in mind that
+
+``swap`` size should be set to either ``total_mem``/3 or 16GB - lower of the two.
+
+``total_mem`` is the total size of the nodes memory.
+
+For example:
+
+* If the node ``total_mem`` is 18GB ``swap`` size should be set to 6GB.
+
+* If the node ``total_mem`` is 240GB ``swap`` size should be set to 16GB.
+
+**Procedure**
+
+#. Create a file that will be used for swap.
+
+ .. code-block:: shell
+
+ sudo fallocate -l 6G /swapfile
+
+#. Change the permissions setting on the file so that only the root user is be able to write and read the swap file.
+
+ .. code-block:: shell
+
+ sudo chmod 600 /swapfile
+
+#. Run the Use *mkswap* utility to set up the file as Linux swap area.
+
+ .. code-block:: shell
+
+ sudo mkswap /swapfile
+
+#. Enable the swap.
+
+ .. code-block:: shell
+
+ sudo swapon /swapfile
+
+#. To make the change sustainable, open the ``/etc/fstab`` file and append the following:
+
+ .. code-block:: shell
+
+ /swapfile swap swap defaults 0 0
+
+#. Verify that swap is active.
+
+ .. code-block:: shell
+
+ sudo swapon --show
+ NAME TYPE SIZE USED PRIO
+ /swapfile file 6024M 507.4M -1
+
+Remove a Swap File
+-------------------
+
+#. Deactivate Swap.
+
+ .. code-block:: none
+
+ sudo swapoff -v /swapfile
+
+#. Remove the sap file entry by editing the ``/etc/fstab`` file and removing ``/swapfile swap swap defaults 0 0``.
+
+#. Delete the swap file.
+
+ .. code-block:: none
+
+ sudo rm /swapfile
+
+
+Additional Information
+----------------------
+
+* `Configure swap for Scylla <https://github.com/scylladb/scylla/blob/master/dist/common/scripts/scylla_swap_setup>`_
+* :doc:`Setup Scripts </getting-started/system-configuration>`.
diff --git a/docs/kb/snapshots.rst b/docs/kb/snapshots.rst
--- a/docs/kb/snapshots.rst
+++ b/docs/kb/snapshots.rst
@@ -0,0 +1,101 @@
+================
+Scylla Snapshots
+================
+
+.. your title should be something customers will search for.
+
+**Topic: snapshots**
+
+.. Give a subtopic for the title (User Management, Security, Drivers, Automation, Optimization, Schema management, Data Modeling, etc.)
+
+**Learn: What are Scylla snapshots? What are they used for? How do they get created and removed?**
+
+
+**Audience: Scylla administrators**
+
+.. Choose (Application Developer, Scylla Administrator, Internal, All)
+
+Synopsis
+--------
+
+Snapshots in Scylla are an essential part of the :doc:`backup and restore mechanism </operating-scylla/procedures/backup-restore/index>`. Whereas in other databases a backup starts with creating a copy of a data file (cold backup, hot backup, shadow copy backup), in Scylla the process starts with creating a table or keyspace snapshot. The snapshots are created either automatically (this is described further in this article) or by invoking the :doc:`nodetool snapshot </operating-scylla/nodetool-commands/snapshot>` command.
+To prevent any issues with restoring your data, the backup strategy must include saving copies of the snapshots on a secondary storage. This makes sure the snapshot is available to restore if the primary storage fails.
+
+.. note:: If you come from RDBMS background you should not confuse snapshots with the notion of materialized views (as they are sometimes called snapshots in that area of technology). With Scylla, snapshots are `hard links <https://en.wikipedia.org/wiki/Hard_link>`_ to data files. :doc:`Materialized views </using-scylla/materialized-views>` do exist in Scylla but they are not called snapshots.
+
+
+How Snapshots Work
+------------------
+
+Scylla, like Cassandra, requires `Unix-like storage <https://en.wikipedia.org/wiki/Unix_filesystem?>`_ (such is also a file system supported by Linux). As mentioned above, snapshots are hard links to SSTables on disk. It is important to understand that SSTables are immutable and as such are not re-written in the same file. When data in database changes and data is written to disk, it is written as a new file. The new files are consolidated following compaction, which merges table’s data into one or more SSTable files (depending on the compaction strategy).
+
+If snapshots (hard links) were created to existing SSTables on disk they are preserved even if table data is eventually stored in one or more of the new SSTables. The :doc:`compaction process </getting-started/compaction>` removes files in the data directory, but the snapshot hard links **will still** be pointing to the **old files**. Only after all of the pointers are removed, the actual file is removed. If even one pointer exists, the file will remain. Therefore, even as the database is moving on, once the snapshot hard links are created, the content of the data files can be copied off to another storage and serve as the foundation for a table, keyspace, or entire database restore (on that node, as this backup and restore process is node specific).
+
+Apart from *planned backup* procedure described above, and as a safeguard from *accidental* loss of data, the Scylla database includes an optional creation of an automatic snapshot every time a table is dropped or truncated. As dropping a keyspace involves dropping tables within that keyspace, these actions will invoke auto snapshots as well. This option is enabled out of the box and is controlled by the auto_snapshot flag in the ``/etc/scylla/scylla.yaml`` configuration file. Note that a keyspace cannot be truncated. It can only be dropped. A table, on the other hand, can be either truncated or dropped. The data in a table can also be deleted, which is different from being truncated.
+
+The default setting for the ``auto_snapshot`` flag in ``/etc/scylla/scylla.yaml`` file is ``true``. It is **not** recommended to set it to ``false``, unless there is a good backup and recovery strategy in place.
+
+Snapshot Creation
+-----------------
+
+Snapshots **are created** when:
+
+* ``nodetool snapshot <keyspace_name>`` runs as this creates snapshots for all tables in the keyspace.
+* ``nodetool snapshot <keyspace_name>.<table_name>`` runs as this creates snapshots for a specific table
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the table is dropped (as in ``DROP TABLE <keyspace_name>.<table_name>`` )
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the table is truncated (as in ``TRUNCATE TABLE <keyspace_name>.<table_name>`` )
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``true`` and the keyspace is dropped (as in ``DROP KEYSPACE <keyspace_name>`` ) - which is the equivalent to dropping all tables in the keyspace and also dropping the keyspace as well.
+
+Snapshots **are not created** when:
+
+* Data in the table is deleted, as opposed to truncated.
+* The ``auto_snapshot`` flag (in scylla.yaml) is set to ``false`` and the table is dropped or truncated.
+
+
+List Current Snapshots
+-----------------------
+
+Snapshot information for tables or keyspaces which are present in the database at the time of invoking the command can be shown with ``nodetool listsnapshots``. Any snapshot which refers to a dropped keyspace or dropped table **cannot** be listed, even if the snapshot still exists on disk (because the database information about these snapshots was deleted but snapshots remain on disk). You can locate these snapshots by looking for the ``snapshot`` directory using a `find <http://man7.org/linux/man-pages/man1/find.1.html>`_ command in Linux.
+
+Remove Snapshots
+----------------
+
+Snapshots are not removed automatically. On active database nodes, old snapshots take up disk space and need to be removed manually to free up the storage space. Snapshots are only taking additional space on disk once the original data files have been changed.
+
+.. caution:: Do not delete snapshots manually at the file system level, use the nodetool command.
+
+Use this procedure to remove snapshots or local backups.
+
+**Procedure**
+
+Use one of the following steps:
+
+To remove a specific snapshot from a specific keyspace:
+
+* Run ``nodetool clearsnapshot -t <snapshot_name> <keyspace_name>``. Note that the snapshot name in this command is a tag, a label, assigned to that snapshot.
+
+To remove the named snapshot from all keyspaces, that is, if any of the keyspaces happen to contain the named snapshot:
+
+* Run ``nodetool clearsnapshot -t <snapshot_name>`` command. Here the keyspace name was omitted.
+
+To remove all existing snapshots without any warning:
+
+* Run ``nodetool clearsnapshot``
+
+.. caution:: use caution when running ``nodetool clearsnapshot`` without specifying a keyspace or snapshot as this command will remove not only snapshots listed by “nodetool listsnapshots” command but all other snapshots on the node’s storage as well, including those for previously dropped tables or keyspaces.
+
+When all else fails, and you need to remove the snapshot manually:
+
+* If database can’t be brought up, it will be impossible for the nodetool command to list or delete snapshots. If, in this situation, the storage must be cleared of old snapshots, the only other remaining way would be removing snapshots manually, at the storage level, with the Linux `rm <http://man7.org/linux/man-pages/man1/rm.1.html>`_ command.
+
+.. note:: After you remove the snapshot with the ``rm`` command and the database which couldn't be brought up returns, ``nodetool listsnapshots`` may still list snapshots that were manually removed.
+
+
+
+Additional References
+---------------------
+
+* :doc:`Taking backups </operating-scylla/procedures/backup-restore/backup>` with snapshots.
+* :doc:`How snapshots are created on demand </operating-scylla/nodetool-commands/snapshot>` (rather than automatically when tables are dropped or truncated).
+* :doc:`Restoring from snapshots </operating-scylla/procedures/backup-restore/restore>`
+
diff --git a/docs/kb/static-columns.rst b/docs/kb/static-columns.rst
--- a/docs/kb/static-columns.rst
+++ b/docs/kb/static-columns.rst
@@ -0,0 +1,18 @@
+Scylla payload sent duplicated static columns
+=============================================
+Scylla payload, which refers to the actual network packets transferred from the Scylla server to the client as a result of a query, contains duplicate static columns.
+
+Issue description
+-----------------
+TCP trace analysis of the response for a query like the one listed below shows duplicate data (e.g., the current timestamp) was sent by the server.
+
+.. code-block:: none
+
+ select some_column, currentTimestamp() from some_table where pk = ?
+
+In another perspective, if you have 10 rows with a static column and a 10KB blob, the entire payload with all non-static columns included will exceed 100KB.
+
+
+Resolution
+----------
+A workaround for this issue would be to select the static column in a second request with LIMIT 1.
diff --git a/docs/kb/stop-local-repair.rst b/docs/kb/stop-local-repair.rst
--- a/docs/kb/stop-local-repair.rst
+++ b/docs/kb/stop-local-repair.rst
@@ -0,0 +1,43 @@
+Stopping a local repair
+=======================
+
+Issuing a stop to a running nodetool repair does not cause an immediate repair stop.
+
+
+Issue description
+-----------------
+
+I have started a local repair using ``nodetool repair``
+
+I have decided to stop the repair by issuing
+
+.. code-block:: sh
+
+ curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 'http://localhost:10000/storage_service/force_terminate_repair'
+
+
+Checking the repair status, I still see the repair running:
+
+.. code-block:: sh
+
+ curl -X GET --header 'Accept: application/json' 'http://localhost:10000/storage_service/active_repair/'
+ [1]
+
+
+Resolution
+----------
+
+**IMPORTANT:** Abort via the http rest api sets the abort flag and the abort does not happen immediately. The repair checks for the abort flag at the beginning of each step, e.g., negotiate_sync_boundary, get_missing_rows_from_follower_nodes, send_missing_rows_to_follower_nodes.
+
+Each step might take a while, so if you abort and check again immediately, the repair in question might still be in RUNNING state.
+
+Please check if the aborted repair stays in RUNNING forever before forcing a stop.
+
+*Force a repair stop:*
+
+.. code-block:: sh
+
+ curl -X POST "http://127.0.0.2:10000/storage_service/force_terminate_repair"
+
+
+**NOTE:** If you are using :doc:`Scylla Manager </operating-scylla/manager/index>` for repairs, a simple stop command via sctool already implements all the needed logic to gracefully stop a repair.
diff --git a/docs/kb/system-limits.rst b/docs/kb/system-limits.rst
--- a/docs/kb/system-limits.rst
+++ b/docs/kb/system-limits.rst
@@ -0,0 +1,20 @@
+System Limits
+-------------
+The following system limits should be set or removed.
+
+======= ============== ========================================
+Name Required value Description
+======= ============== ========================================
+core unlimited maximum core dump size
+------- -------------- ----------------------------------------
+memlock unlimited maximum locked-in-memory address space
+------- -------------- ----------------------------------------
+nofile 200000 maximum number of open file descriptors
+------- -------------- ----------------------------------------
+as unlimited address space limit
+------- -------------- ----------------------------------------
+nproc 8096 maximum number of processes
+======= ============== ========================================
+
+This configuration is provided in the file :code:`/etc/security/limits.d/scylla.conf`.
+
diff --git a/docs/kb/tombstones-flush.rst b/docs/kb/tombstones-flush.rst
--- a/docs/kb/tombstones-flush.rst
+++ b/docs/kb/tombstones-flush.rst
@@ -0,0 +1,51 @@
+=============================================
+How to flush old tombstones from a table
+=============================================
+
+**Audience: Devops professionals, architects**
+
+Description
+-----------
+If you have large partitions with lots of tombstones, you can use this workaround to flush the old tombstones.
+To avoid data resurrection, make sure that tables are repaired (either with nodetool repair or Scylla Manager) before the ``gc_grace_seconds`` threshold is reached.
+After the repair finishes, any tombstone older than the previous repair can be flushed.
+
+.. note:: Use :doc:`this article </troubleshooting/large-partition-table/>` to help you find large partitions.
+
+Steps:
+^^^^^^
+1. Run nodetool repair to synchronize the data between nodes. Alternatively, you can use Scylla Manager to run a repair.
+
+.. code-block:: sh
+
+ nodetool repair <options>;
+
+2. Set the ``gc_grace_seconds`` to the time since last repair was started - For instance, if the last repair was executed one day ago, then set ``gc_grace_seconds`` to one day (86400sec). For more information, please refer to :doc:`this KB article </kb/gc-grace-seconds/>`.
+
+.. note:: To prevent the compaction of unsynched tombstones, it is important to get the timing correctly. If you are not sure what time should set, please contact `Scylla support <https://www.scylladb.com/product/support/>`_.
+
+.. code-block:: sh
+
+ ALTER TABLE <keyspace>.<mytable> WITH gc_grace_seconds = <newTimeValue>;
+
+.. note:: Steps 3 & 4 should be repeated on ALL nodes affected with large tombstone partitions.
+
+3. Run nodetool flush
+
+.. code-block:: sh
+
+ nodetool flush <keyspace>.<mytable>;
+
+4. Run compaction (this will remove big partitions with tombstones from specified table)
+
+.. note:: By default, major compaction runs on all the keyspaces and tables, so if we want to specyfy e.g. only one table, we should point at it using arguments: ``<keyspace>.<mytable>``. For more information, please refer to `this article <https://docs.scylladb.com/operating-scylla/nodetool-commands/compact/>`_.
+
+.. code-block:: sh
+
+ nodetool compact <keyspace>.<mytable>;
+
+5. Alter the table and change the grace period back to the original ``gc_grace_seconds`` value.
+
+.. code-block:: sh
+
+ ALTER TABLE <keyspace>.<mytable> WITH gc_grace_seconds = <oldValue>;
diff --git a/docs/kb/ttl-facts.rst b/docs/kb/ttl-facts.rst
--- a/docs/kb/ttl-facts.rst
+++ b/docs/kb/ttl-facts.rst
@@ -0,0 +1,91 @@
+=================================
+Time to Live (TTL) and Compaction
+=================================
+
+**Topic: TTL, gc_grace_seconds, and Compaction**
+
+**Learn: How data is removed when using TTL**
+
+**Audience: All**
+
+
+Synopsis
+--------
+It is not always clear under which circumstances data is deleted when using Time to Live (TTL) and :ref:`gc_grace_seconds <gc_grace_seconds>` arguments in table definitions.
+This article clarifies what may not be apparent.
+It corrects some assumptions you may have that are not exactly true.
+
+
+Facts About Expiring Data
+-------------------------
+
+#. When compaction is running on an SSTable and it scans a piece of data that has expired the following happens:
+
+ * If the `data time stamp + gc_grace_seconds` is less than or equal to the current time (now), the data is thrown away and a tombstone is **not** created.
+ * If not, a tombstone is created and its timestamp is the same as its corresponding data. This means that the tombstone is going to be deleted after (at least) gc_grace_seconds from the time when the corresponding data element has been written.
+
+ For example:
+
+ In this example there is an expired cell that becomes a tombstone, note how the tombstone's local_deletion_time is the expired cell's timestamp.
+
+ .. code-block:: none
+
+ "rows" : [
+ {
+ "type" : "row",
+ "position" : 120,
+ "liveness_info" : { "tstamp" : "2017-04-09T17:07:12.702597Z",
+ "ttl" : 20, "expires_at" : "2017-04-09T17:07:32Z", "expired" : true },
+ "cells" : [
+ { "name" : "country", "value" : "1" },
+ ]
+
+ Is compacted into:
+
+ .. code-block:: none
+
+
+ "rows" : [
+ {
+ "type" : "row",
+ "position" : 79,
+ "cells" : [
+ { "name" : "country", "deletion_info" :
+ { "local_delete_time" : "2017-04-09T17:07:12Z" },
+ "tstamp" : "2017-04-09T17:07:12.702597Z"
+ },
+ ]
+
+#. If you set the TTL to be *greater* than the gc_grace_seconds, the expired data will **never** generate a tombstone.
+
+ Example: When Time Window Compaction Strategy (TWCS) estimates if a particular SSTable can be deleted it is going to treat expired data similarly as a tombstone:
+
+ .. code-block:: none
+
+ gc grace seconds: 0
+ sstable A: token range: [10, 10], timestamp range: [1, 1], ttl: 2, max deletion time: 3 (1+2)
+ sstable B: token range: [10, 10], timestamp range: [1, 5], ttl: 2, max deletion time: 7 (5+2)
+ now: 6
+
+ From this you can see that:
+
+ * SSTable A is fully expired because its max deletion time (3) is lower than now (6).
+ * SSTable B is NOT fully expired because its max deletion time (7) is greater than now (6).
+ * SSTable A will be added as a candidate for fully expired SSTable and will be purged.
+
+ During Compaction:
+
+ * Compaction sees that SSTable B overlaps with SSTable A in token range.
+ * Compaction also sees that SSTable A overlaps with B in timestamp range, and it thinks that SSTable A could have a tombstone that shadows data in SSTable B.
+ * Compaction decides not to purge SSTable A even though it's fully expired.
+
+#. If you use updates in conjunction with TWCS, it may prevent the "window compacted" SSTables from being deleted when they should have been.
+ However, when the corresponding data expires (in all SSTables), all relevant SSTables are will be deleted during the next compaction.
+
+
+Additional Information
+----------------------
+
+* :doc:`How to Change gc_grace_seconds for a Table </kb/gc-grace-seconds/>`
+* :doc:`Expiring Data with Time to Live (TTL) </getting-started/time-to-live/>`
+* :ref:`CQL Reference: Table Options <create-table-general-options>`
diff --git a/docs/kb/unresponsive-nodes.rst b/docs/kb/unresponsive-nodes.rst
--- a/docs/kb/unresponsive-nodes.rst
+++ b/docs/kb/unresponsive-nodes.rst
@@ -0,0 +1,51 @@
+==============================
+Scylla Nodes are Unresponsive
+==============================
+
+**Topic: Performance Analysis**
+
+**Issue:**
+
+Scylla nodes are unresponsive. They are shown as down, and I can't even establish new SSH connections to the cluster. The existing connections are slow.
+
+**Environment: All**
+
+
+
+Root Cause
+----------
+
+When Scylla is reporting itself as down, this may mean a Scylla-specific issue. But when the node as a whole starts reporting slowness and even establishing SSH connections is hard, that usually indicates a node level issue.
+
+The most common cause is due to swap. There are two main situations we need to consider:
+
+* The system has swap configured. If the system needs to swap pages, it may swap the Scylla memory, and future access to that memory will be slow.
+
+* The system does not have swap configured. In that case the kernel may go on a loop trying to free pages without being able to so, becoming a CPU-hog which eventually stalls the Scylla and other processes from executing.
+
+
+
+Resolution
+----------
+
+1. Ideally, a healthy system should not swap. Scylla pre-allocates 93% of the memory by default, and never uses more than that. It leaves the remaining 7% of the memory for other tasks including the Operating System. Check with the ``top`` utility if there are other processes running which are consuming a lot of memory.
+
+ * If there are other processes running but they are not essential, we recommend moving them to other machines.
+ * If there are other processes running and they are essential, the default reservation may not be enough. Change the reservation following the steps below.
+
+
+ Swap can be set up in several ways. One way to set up swap is detailed in the KB Article :doc:`How to Setup a Swap Space </kb/set-up-swap>`.
+
+
+2. Having swap enabled and not using it is better than needing swap and not having it. Configure a file or partition to be used as swap for production deployments.
+
+Change memory reservation
+-------------------------
+
+Add ``--reserve-memory [memory]`` to the scylla command line at:
+
+* ``/etc/sysconfig/scylla-server`` (RHEL variants) or
+* ``/etc/defaults/scylla-server`` (Debian variants)
+
+For example ``--reserve-memory 10G`` (will reserve 10G)
+
diff --git a/docs/kb/update-pk.rst b/docs/kb/update-pk.rst
--- a/docs/kb/update-pk.rst
+++ b/docs/kb/update-pk.rst
@@ -0,0 +1,17 @@
+==============================
+Update a Primary Key
+==============================
+
+**Topic: Can you Update a Primary Key in Scylla?**
+
+**Audience: Scylla administrators**
+
+In Scylla, you cannot update a primary key. It is impossible to do so.
+
+However, you can migrate the data from the old table with the old primary key to a new table with a new primary key.
+There are two ways to handle the migration:
+
+* Fork-lifting the historical data with the :doc:`Spark Migrator </using-scylla/mig-tool-review/>` tool.
+* Double writing the new data.
+
+If you are running Scylla Enterprise it is advantageous to control the migration resources using :doc:`Workload Prioritization </using-scylla/workload-prioritization/>`.
diff --git a/docs/kb/use-perf.rst b/docs/kb/use-perf.rst
--- a/docs/kb/use-perf.rst
+++ b/docs/kb/use-perf.rst
@@ -0,0 +1,60 @@
+==================================
+Using the perf utility with Scylla
+==================================
+
+.. meta::
+ :title:
+ :description: Debugging or Diving into a Pegged Shard
+ :keywords: perf, pegged shard, list processes, analyze perf issue
+
+This article contains useful tips & tricks for using the `perf` utility with Scylla.
+The `perf` utility is particularly useful when debugging a pegged shard.
+
+
+Due to its thread-per-core nature, looking at aggregates is rarely useful as it tends to hide bad behavior that is localized to specific CPUs. Looking at an individual CPU will make those anomalies easier to see. Once you notice that a Scylla shard requires investigation (for example, when the Scylla Monitor shard view shows that a particular shard is more loaded than others), you can use the ``seastar-cpu-map.sh`` script described :doc:`here </kb/map-cpu/>` to determine which Linux CPU hosts that Scylla shard. For example:
+.. code-block:: bash
+
+ seastar-cpu-map.sh -n scylla -s 0
+
+Output:
+
+.. code-block:: console
+ :class: hide-copy-button
+
+ shard: 0, cpu: 1
+
+In the above example, shard 0 is investigated using the ``-s`` argument and providing the shard number. The results show that shard 0 runs on Linux CPU 1. In all ``perf`` commands that follow, you can add the ``-C 1`` argument to restrict ``perf`` to look only at CPU 1.
+
+When is perf useful?
+--------------------
+
+`Perf`` is most useful when the CPU being probed runs at 100% utilization so that you can identify large chunks of execution time used by particular functions.
+
+Note that due to polling, Scylla will easily drive CPUs to 100% even when it is not bottlenecked. It will spin (poll) for some time, waiting for new requests. It tends to show in the perf reports as functions related to polling having high CPU time.
+
+Perf can also be a useful tool when you suspect that something that shouldn’t be running is running. One example is systems with very high ``reactor_utilization`` (indicating non-polling work), where the Linux view of ``system`` CPU utilization is also high. It indicates that the Linux Kernel, not Scylla, is the main user of the CPU, so additional investigation is needed.
+
+perf top
+--------
+
+Perf top shows a point-in-time view of the system. The figure below shows the result of running ``perf top -C 1``.
+
+.. image:: perf-top.png
+
+Callgraphs
+----------
+
+``Perf`` can generate callgraphs. They are useful when you want to understand the complete call chain that results in a function being called. You can add ``--call-graph=dwarf -F 99`` to any recording command, such as ``perf top`` or ``perf record``, to generate a callgraph.
+
+For example, to record the callgraphs in CPU2:
+
+.. code-block:: bash
+
+ sudo perf record -C 2 --call-graph=dwarf -F 99
+
+You can dump the results to the ``trace.txt`` file by running:
+
+.. code-block:: bash
+
+ sudo perf report --no-children --stdio > /tmp/trace.txt
+
diff --git a/docs/kb/write-path-image-memtable-sstable.png b/docs/kb/write-path-image-memtable-sstable.png
--- a/docs/kb/write-path-image-memtable-sstable.png
+++ b/docs/kb/write-path-image-memtable-sstable.png
null
diff --git a/docs/kb/yaml-address.rst b/docs/kb/yaml-address.rst
--- a/docs/kb/yaml-address.rst
+++ b/docs/kb/yaml-address.rst
@@ -0,0 +1,71 @@
+
+Configure Scylla Networking with Multiple NIC/IP Combinations
+=============================================================
+
+There are many ways to configure IP addresses in scylla.yaml. Setting the IP addresses incorrectly, can yield less than optimal results. This article focuses on configuring the addresses which are vital to network communication.
+
+This article contains examples of the different ways to configure networking in scylla.yaml. The entire scope for address configuration is in the :ref:`Admin guide <admin-address-configuration-in-scylla>`.
+
+As these values depend on a particular network configuration in your setup there are a few ways to configure the address parameters. In the examples below, we will provide instructions for the most common use cases (all in the resolution of a single Scylla node).
+
+1 NIC, 1 IP
+-----------
+
+This is the case where a Scylla cluster is meant to operate in a single subnet with a single address space (no "public/internal IP"s).
+
+In this case:
+
+* IP = node's IP address
+
+.. code-block:: none
+
+ listen_address: IP
+ rpc_address: IP
+ broadcast_address: not set
+ broadcast_rpc_address: not set
+ endpoint_snitch: no restrictions
+
+1 NIC, 2 IPs
+------------
+
+This is the case where you are using Public and Internal IP addresses. AWS instances with public IP addresses is a classic example of this configuration.
+
+In this case:
+
+* IPp = the node's public IP address
+* IPi = the node's internal IP address
+
+IPi is the IP configured to the same IP as the NIC (from the OS perspective) and when running the ip command, the output displays this IP address. For ip command parameters, refer to your Linux distro documentation.
+
+.. code-block:: none
+
+ listen_address: IPi
+ rpc_address: IPi
+ broadcast_address: IPp
+ broadcast_rpc_address: IPp
+ endpoint_snitch: GossipintPropertyFileSnitch with prefer_local=true | any of Ec2xxxSnitch snitches.
+
+2 NICs, 2 IPs
+-------------
+
+This is the case where a user wants CQL requests or responses to be sent via one subnet (net1) and inter-node communication to go over another subnet (net2).
+
+In this case:
+
+* IP1 = node's IP in net1 subnet
+* IP2 = node's IP in net2 subnet
+
+.. code-block:: none
+
+ listen_address: IP2
+ rpc_address: IP1
+ broadcast_address: not set
+ broadcast_rpc_address: not set
+ endpoint_snitch: no restrictions
+
+
+Additional References
+---------------------
+
+:doc:`Administration Guide </operating-scylla/admin>` - User guide for Scylla Administration
+
diff --git a/docs/operating-scylla/_common/decommission_warning.rst b/docs/operating-scylla/_common/decommission_warning.rst
--- a/docs/operating-scylla/_common/decommission_warning.rst
+++ b/docs/operating-scylla/_common/decommission_warning.rst
@@ -0,0 +1,4 @@
+.. warning::
+
+ Review current disk space utilization on existing nodes and make sure the amount of data streamed from the node being removed can fit into the disk space available on the remaining nodes. If there is not enough disk space on the remaining nodes, the removal of a node will fail. Add more storage to remaining nodes **before** starting the removal procedure.
+
diff --git a/docs/operating-scylla/_common/networking-ports.rst b/docs/operating-scylla/_common/networking-ports.rst
--- a/docs/operating-scylla/_common/networking-ports.rst
+++ b/docs/operating-scylla/_common/networking-ports.rst
@@ -0,0 +1,30 @@
+
+Scylla uses the following ports:
+
+====== ============================================ ========
+Port Description Protocol
+====== ============================================ ========
+9042 CQL (native_transport_port) TCP
+------ -------------------------------------------- --------
+9142 SSL CQL (secure client to node) TCP
+------ -------------------------------------------- --------
+7000 Inter-node communication (RPC) TCP
+------ -------------------------------------------- --------
+7001 SSL inter-node communication (RPC) TCP
+------ -------------------------------------------- --------
+7199 JMX management TCP
+------ -------------------------------------------- --------
+10000 Scylla REST API TCP
+------ -------------------------------------------- --------
+9180 Prometheus API TCP
+------ -------------------------------------------- --------
+9100 node_exporter (Optionally) TCP
+------ -------------------------------------------- --------
+9160 Scylla client port (Thrift) TCP
+------ -------------------------------------------- --------
+19042 Native shard-aware transport port TCP
+------ -------------------------------------------- --------
+19142 Native shard-aware transport port (ssl) TCP
+====== ============================================ ========
+
+.. note:: For Scylla Manager ports, see `Scylla Manager <https://scylladb.github.io/scylla-manager/>`_.
diff --git a/docs/operating-scylla/_common/tools_index.rst b/docs/operating-scylla/_common/tools_index.rst
--- a/docs/operating-scylla/_common/tools_index.rst
+++ b/docs/operating-scylla/_common/tools_index.rst
@@ -0,0 +1,21 @@
+* :doc:`Nodetool Reference</operating-scylla/nodetool>` - Scylla commands for managing Scylla node or cluster using the command-line nodetool utility.
+* :doc:`CQLSh - the CQL shell</getting-started/cqlsh>`.
+* :doc:`REST - Scylla REST/HTTP Admin API</operating-scylla/rest>`.
+* :doc:`Tracing </using-scylla/tracing>` - a ScyllaDB tool for debugging and analyzing internal flows in the server.
+* :doc:`SSTableloader </operating-scylla/admin-tools/sstableloader>` - Bulk load the sstables found in the directory to a Scylla cluster
+* :doc:`scylla-sstable </operating-scylla/admin-tools/scylla-sstable>` - Validates and dumps the content of SStables, generates a histogram, dumps the content of the SStable index.
+* :doc:`scylla-types </operating-scylla/admin-tools/scylla-types/>` - Examines raw values obtained from SStables, logs, coredumps, etc.
+* :doc:`cassandra-stress </operating-scylla/admin-tools/cassandra-stress/>` A tool for benchmarking and load testing a Scylla and Cassandra clusters.
+* :doc:`SSTabledump - Scylla 3.0, Scylla Enterprise 2019.1 and newer versions </operating-scylla/admin-tools/sstabledump>`
+* :doc:`SSTable2JSON - Scylla 2.3 and older </operating-scylla/admin-tools/sstable2json>`
+* sstablelevelreset - Reset level to 0 on a selected set of SSTables that use LeveledCompactionStrategy (LCS).
+* :doc:`SSTable-Index </operating-scylla/admin-tools/sstable-index>` - A tool which lists all partitions contained in an SSTable index.
+* sstablemetadata - Prints metadata about a specified SSTable.
+* sstablerepairedset - Mark specific SSTables as repaired or unrepaired.
+* configuration_encryptor - :doc:`encrypt at rest </operating-scylla/security/encryption-at-rest>` sensitive scylla configuration entries using system key.
+* local_file_key_generator - Generate a local file (system) key for :doc:`encryption at rest </operating-scylla/security/encryption-at-rest>`, with the provided length, Key algorithm, Algorithm block mode and Algorithm padding method.
+* `scyllatop <https://www.scylladb.com/2016/03/22/scyllatop/>`_ - A terminal base top-like tool for scylladb collectd/prometheus metrics.
+* :doc:`scylla_dev_mode_setup</getting-started/install-scylla/dev-mod>` - run Scylla in Developer Mode.
+* :doc:`perftune</operating-scylla/admin-tools/perftune>` - performance configuration.
+
+Run each tool with ``-h``, ``--help`` for full options description.
diff --git a/docs/operating-scylla/admin-tools/cassandra-stress.rst b/docs/operating-scylla/admin-tools/cassandra-stress.rst
--- a/docs/operating-scylla/admin-tools/cassandra-stress.rst
+++ b/docs/operating-scylla/admin-tools/cassandra-stress.rst
@@ -0,0 +1,277 @@
+Cassandra Stress
+================
+
+The cassandra-stress tool is used for benchmarking and load testing both Scylla and Cassandra clusters. The cassandra-stress tool also supports testing arbitrary CQL tables and queries to allow users to benchmark their data model.
+
+This documentation focuses on user mode as this allows the testing of your actual schema.
+
+Usage
+-----
+
+There are several operation types:
+
+* write-only, read-only, and mixed workloads of standard data
+* write-only and read-only workloads for counter columns
+* user configured workloads, running custom queries on custom schemas
+* The syntax is cassandra-stress <command> [options]. If you want more information on a given command or options, just run cassandra-stress help
+
+Commands:
+
+read: Multiple concurrent reads - the cluster must first be populated by a write test.
+
+write: Multiple concurrent writes against the cluster.
+
+mixed: Interleaving of any basic commands, with configurable ratio and distribution - the cluster must first be populated by a write test.
+
+counter_write: Multiple concurrent updates of counters.
+
+counter_read: Multiple concurrent reads of counters. The cluster must first be populated by a counterwrite test.
+
+user: Interleaving of user provided queries, with configurable ratio and distribution.
+
+help: Print help for a command or option.
+
+print: Inspect the output of a distribution definition.
+
+legacy: Legacy support mode.
+
+Primary Options:
+
+-pop: Population distribution and intra-partition visit order.
+
+-insert: Insert specific options relating to various methods for batching and splitting partition updates.
+
+-col: Column details such as size and count distribution, data generator, names, comparator and if super columns should be used.
+
+-rate: Thread count, rate limit or automatic mode (default is auto).
+
+-mode: Thrift or CQL with options.
+
+-errors: How to handle errors when encountered during stress.
+
+-sample: Specify the number of samples to collect for measuring latency.
+
+-schema: Replication settings, compression, compaction, etc.
+
+-node: Nodes to connect to.
+
+-log: Where to log progress to, and the interval at which to do it.
+
+-transport: Custom transport factories.
+
+-port: The port to connect to cassandra nodes on.
+
+-sendto: Specify a stress server to send this command to.
+
+-graph: Graph recorded metrics.
+
+-tokenrange: Token range settings.
+
+User mode
+---------
+
+User mode allows you to use your stress your own schemas. This can save time in the long run rather than building an application and then realising your schema doesn’t scale.
+
+Profile
+.......
+
+User mode requires a profile defined in YAML. Multiple YAML files may be specified in which case operations in the ops argument are referenced as specname.opname.
+
+An identifier for the profile:
+
+.. code-block:: cql
+
+ specname: staff_activities
+
+The keyspace for the test:
+
+.. code-block:: cql
+
+ keyspace: staff
+
+CQL for the keyspace. Optional if the keyspace already exists:
+
+.. code-block:: cql
+
+ keyspace_definition: |
+ CREATE KEYSPACE stresscql WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};
+
+The table to be stressed:
+
+.. code-block:: cql
+
+ table: staff_activities
+
+CQL for the table. Optional if the table already exists:
+
+.. code-block:: cql
+
+ table_definition: |
+ CREATE TABLE staff_activities (
+ name text,
+ when timeuuid,
+ what text,
+ PRIMARY KEY(name, when, what)
+ )
+
+Optional meta information on the generated columns in the above table. The min and max only apply to text and blob types. The distribution field represents the total unique population distribution of that column across rows:
+
+.. code-block:: cql
+
+ columnspec:
+ - name: name
+ size: uniform(5..10) # The names of the staff members are between 5-10 characters
+ population: uniform(1..10) # 10 possible staff members to pick from
+ - name: when
+ cluster: uniform(20..500) # Staff members do between 20 and 500 events
+ - name: what
+ size: normal(10..100,50)
+
+Supported types are:
+
+An exponential distribution over the range [min..max]:
+
+.. code-block:: cql
+
+ EXP(min..max)
+
+An extreme value (Weibull) distribution over the range [min..max]:
+
+.. code-block:: cql
+
+ EXTREME(min..max,shape)
+
+A gaussian/normal distribution, where mean=(min+max)/2, and stdev is (mean-min)/stdvrng:
+
+.. code-block:: cql
+
+ GAUSSIAN(min..max,stdvrng)
+
+A gaussian/normal distribution, with explicitly defined mean and stdev:
+
+.. code-block:: cql
+
+ GAUSSIAN(min..max,mean,stdev)
+
+A uniform distribution over the range [min, max]:
+
+.. code-block:: cql
+
+ UNIFORM(min..max)
+
+A fixed distribution, always returning the same value:
+
+.. code-block:: cql
+
+ FIXED(val)
+
+If preceded by ~, the distribution is inverted
+
+Defaults for all columns are size: uniform(4..8), population: uniform(1..100B), cluster: fixed(1)
+
+Insert distributions:
+
+.. code-block:: cql
+
+ insert:
+ # How many partition to insert per batch
+ partitions: fixed(1)
+ # How many rows to update per partition
+ select: fixed(1)/500
+ # UNLOGGED or LOGGED batch for insert
+ batchtype: UNLOGGED
+
+Currently all inserts are done inside batches.
+
+Read statements to use during the test:
+
+.. code-block:: cql
+
+ queries:
+ events:
+ cql: select * from staff_activities where name = ?
+ fields: samerow
+ latest_event:
+ cql: select * from staff_activities where name = ? LIMIT 1
+ fields: samerow
+
+Running a user mode test:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./example.yaml duration=1m "ops(insert=1,latest_event=1,events=1)" truncate=once
+
+This will create the schema then run tests for 1 minute with an equal number of inserts, latest_event queries and events queries. Additionally the table will be truncated once before the test.
+
+The full example can be found here yaml
+
+Running a user mode test with multiple yaml files:
+
+.. code-block::
+
+ cassandra-stress user profile=./example.yaml,./example2.yaml duration=1m “ops(ex1.insert=1,ex1.latest_event=1,ex2.insert=2)” truncate=once
+
+This will run operations as specified in both the example.yaml and example2.yaml files. example.yaml and example2.yaml can reference the same table
+although care must be taken that the table definition is identical (data generation specs can be different).
+
+.. Lightweight transaction support
+.. ...............................
+
+.. cassandra-stress supports lightweight transactions. In this it will first read current data from Cassandra and then uses read value(s) to fulfill lightweight transaction condition(s).
+
+.. Lightweight transaction update query:
+
+.. .. code-block:: cql
+
+.. queries:
+.. regularupdate:
+.. cql: update blogposts set author = ? where domain = ? and published_date = ?
+.. fields: samerow
+.. updatewithlwt:
+.. cql: update blogposts set author = ? where domain = ? and published_date = ? IF body = ? AND url = ?
+.. fields: samerow
+
+Graphing
+........
+
+Graphs can be generated for each run of stress.
+
+.. image:: example-stress-graph.png
+
+To create a new graph:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./stress-example.yaml "ops(insert=1,latest_event=1,events=1)" -graph file=graph.html title="Awesome graph"
+
+To add a new run to an existing graph point to an existing file and add a revision name:
+
+.. code-block:: cql
+
+ cassandra-stress user profile=./stress-example.yaml duration=1m "ops(insert=1,latest_event=1,events=1)" -graph file=graph.html title="Awesome graph" revision="Second run"
+
+FAQ
+...
+
+How do you use NetworkTopologyStrategy for the keyspace?
+
+Use the schema option making sure to either escape the parenthesis or enclose in quotes:
+
+.. code-block:: cql
+
+ cassandra-stress write -schema "replication(strategy=NetworkTopologyStrategy,datacenter1=3)"
+
+How do you use SSL?
+
+Use the transport option:
+
+.. code-block:: cql
+
+ cassandra-stress "write n=100k cl=ONE no-warmup" -transport "truststore=$HOME/jks/truststore.jks truststore-password=cassandra"
+
+
+
+.. include:: /rst_include/apache-copyrights.rst
+
+
+
diff --git a/docs/operating-scylla/admin-tools/example-stress-graph.png b/docs/operating-scylla/admin-tools/example-stress-graph.png
--- a/docs/operating-scylla/admin-tools/example-stress-graph.png
+++ b/docs/operating-scylla/admin-tools/example-stress-graph.png
null
diff --git a/docs/operating-scylla/admin-tools/index.rst b/docs/operating-scylla/admin-tools/index.rst
--- a/docs/operating-scylla/admin-tools/index.rst
+++ b/docs/operating-scylla/admin-tools/index.rst
@@ -0,0 +1,31 @@
+Admin Tools
+============
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ Nodetool Reference </operating-scylla/nodetool>
+ CQLSh </getting-started/cqlsh>
+ REST </operating-scylla/rest>
+ Tracing </using-scylla/tracing>
+ scylla-sstable
+ scylla-types </operating-scylla/admin-tools/scylla-types/>
+ sstableloader
+ cassandra-stress </operating-scylla/admin-tools/cassandra-stress/>
+ sstabledump
+ sstable2json
+ sstable-index
+ Scylla Logs </getting-started/logging/>
+ perftune
+ Virtual Tables </operating-scylla/admin-tools/virtual-tables/>
+
+
+.. panel-box::
+ :title: Admin Tools
+ :id: "getting-started"
+ :class: my-panel
+
+ .. include:: /operating-scylla/_common/tools_index.rst
+
+The `Admin Procedures and Monitoring lesson <https://university.scylladb.com/courses/scylla-operations/lessons/admin-procedures-and-basic-monitoring/topic/admin-procedures-and-monitoring/>`_ on Scylla University provides more training and examples material on this subject.
diff --git a/docs/operating-scylla/admin-tools/perftune.rst b/docs/operating-scylla/admin-tools/perftune.rst
--- a/docs/operating-scylla/admin-tools/perftune.rst
+++ b/docs/operating-scylla/admin-tools/perftune.rst
@@ -0,0 +1,51 @@
+Seastar Perftune
+================
+
+Configure various system parameters to improve the seastar application performance, called from of scylla_setup script.
+
+This script will:
+
+* Ban relevant IRQs from being moved by irqbalance.
+* Configure various system parameters in /proc/sys.
+* Distribute the IRQs (using SMP affinity configuration) among CPUs according to the configuration mode (see below).
+
+As a result, some of the CPUs may be destined only to handle the IRQs and taken out of the CPU set to be used to run the seastar application ("compute CPU set").
+
+
+perftune.py [options]
+
+Options:
+
+* ``--mode`` - configuration mode (see below)
+* ``--nic`` - network interface name(s), by default uses *eth0* (may appear more than once)
+* ``--tune-clock`` - Force tuning of the system clocksource
+* ``--get-cpu-mask`` - print the CPU mask to be used for compute
+* ``--get-cpu-mask-quiet`` - print the CPU mask to be used for compute, print the zero CPU set if that's what it turns out to be
+* ``--verbose`` - be more verbose about operations and their result
+* ``--tune`` - components to configure (may be given more than once)
+* ``--cpu-mask`` - mask of cores to use, by default use all available cores
+* ``--irq-cpu-mask``- mask of cores to use for IRQs binding
+* ``--dir`` - directory to optimize (may appear more than once)
+* ``--dev`` device to optimize (may appear more than once), e.g. sda1
+* ``--options-file`` - configuration YAML file
+* ``--dump-options-file`` - Print the configuration YAML file containing the current configuration
+* ``--dry-run`` - Don't take any action, just recommend what to do
+* ``--write-back-cache`` Enable/Disable *write back* write cache mode
+
+Modes description:
+
+* *sq* - set all IRQs of a given NIC to CPU0 and configure RPS to spreads NAPIs' handling between other CPUs.
+* *sq_split* - divide all IRQs of a given NIC between CPU0 and its HT siblings and configure RPS to spreads NAPIs' handling between other CPUs.
+* *mq* - distribute NIC's IRQs among all CPUs instead of binding them all to CPU0. In this mode RPS is always enabled to spreads NAPIs' handling between all CPUs.
+
+If there isn't any mode given script will use a default mode:
+
+- If number of physical CPU cores per Rx HW queue is greater than 4 - use the 'sq-split' mode.
+- Otherwise, if number of hyperthreads per Rx HW queue is greater than 4 - use the 'sq' mode.
+- Otherwise use the 'mq' mode.
+
+Default values:
+
+* --nic NIC: eth0
+* --cpu-mask MASK: all available cores mask
+* --tune-clock: false
diff --git a/docs/operating-scylla/admin-tools/scylla-sstable.rst b/docs/operating-scylla/admin-tools/scylla-sstable.rst
--- a/docs/operating-scylla/admin-tools/scylla-sstable.rst
+++ b/docs/operating-scylla/admin-tools/scylla-sstable.rst
@@ -0,0 +1,72 @@
+scylla-sstable
+==============
+
+.. versionadded:: 5.0
+
+Introduction
+-------------
+
+This tool allows you to examine the content of SStables by performing operations such as dumping the content of SStables,
+generating a histogram, validating the content of SStables, and more. See `Supported Operations`_ for the list of available operations.
+
+Run ``scylla-sstable --help`` for additional information about the tool and the operations.
+
+Usage
+------
+
+Syntax
+^^^^^^
+
+The command syntax is as follows:
+
+.. code-block:: console
+
+ scylla-sstable <operation> <path to SStable>
+
+
+You can specify more than one SStable.
+
+Supported Operations
+^^^^^^^^^^^^^^^^^^^^^^^
+The ``dump-*`` operations output JSON. For ``dump-data``, you can specify another output format.
+
+* ``dump-data`` - Dumps the content of the SStable. You can use it with additional parameters:
+
+ * ``--merge`` - Allows you to process multiple SStables as a unified stream (if not specified, multiple SStables are processed one by one).
+ * ``--partition={{<partition key>}}`` or ``partitions-file={{<partition key>}}`` - Allows you to narrow down the scope of the operation to specified partitions. To specify the partition(s) you want to be processed, provide partition keys in the hexdump format used by ScyllaDB (the hex representation of the raw buffer).
+ * ``--output-format=<format>`` - Allows you to specify the output format: ``json`` or ``text``.
+
+* ``dump-index`` - Dumps the content of the SStable index.
+* ``dump-compression-info`` - Dumps the SStable compression information, including compression parameters and mappings between
+ compressed and uncompressed data.
+* ``dump-summary`` - Dumps the summary of the SStable index.
+* ``dump-statistics`` - Dumps the statistics of the SStable, including metadata about the data component.
+* ``dump-scylla-metadata`` - Dumps the SStable's scylla-specific metadata.
+* ``writetime-histogram`` - Generates a histogram of all the timestamps in the SStable. You can use it with a parameter:
+
+ * ``--bucket=<unit>`` - Allows you to specify the unit of time to be used as bucket (years, months, weeks, days, or hours).
+
+* ``validate`` - Validates the content of the SStable with the mutation fragment stream validator.
+* ``validate-checksums`` - Validates SStable checksums (full checksum and per-chunk checksum) against the SStable data.
+* ``decompress`` - Decompresses the data component of the SStable (the ``*-Data.db`` file) if compressed. The decompressed data is written to a ``*-Data.decompressed`` file.
+
+Examples
+^^^^^^^^
+Dumping the content of the SStable:
+
+.. code-block:: console
+
+ scylla-sstable dump-data /path/to/md-123456-big-Data.db
+
+Dumping the content of two SStables as a unified stream:
+
+.. code-block:: console
+
+ scylla-sstable dump-data --merge /path/to/md-123456-big-Data.db /path/to/md-123457-big-Data.db
+
+
+Validating the specified SStables:
+
+.. code-block:: console
+
+ scylla-sstable validate /path/to/md-123456-big-Data.db /path/to/md-123457-big-Data.db
diff --git a/docs/operating-scylla/admin-tools/scylla-types.rst b/docs/operating-scylla/admin-tools/scylla-types.rst
--- a/docs/operating-scylla/admin-tools/scylla-types.rst
+++ b/docs/operating-scylla/admin-tools/scylla-types.rst
@@ -0,0 +1,140 @@
+scylla-types
+==============
+
+.. versionadded:: 5.0
+
+Introduction
+-------------
+This tool allows you to examine raw values obtained from SStables, logs, coredumps, etc., by performing operations on them,
+such as ``print``, ``compare``, or ``validate``. See :ref:`Supported Operations <scylla-types-operations>` for details.
+
+Run ``scylla types --help`` for additional information about the tool and the operations.
+
+Usage
+------
+
+Syntax
+^^^^^^
+
+The command syntax is as follows:
+
+.. code-block:: console
+
+ scylla types <operation> [options] <hex_value1> [hex_value2]
+
+
+* Provide the values in the hex form without a leading 0x prefix.
+* You must specify the type of the provided values. See :ref:`Specifying the Value Type <scylla-types-type>`.
+* The number of provided values depends on the operation. See :ref:`Supported Operations <scylla-types-operations>` for details.
+* The scylla-types operations come with additional options. See :ref:`Additional Options <scylla-types-options>` for the list of options.
+
+.. _scylla-types-type:
+
+Specifying the Value Type
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You must specify the type of the value(s) you want to examine by adding the ``-t [type name]`` option to the operation.
+Specify the type by providing its Cassandra class name (the prefix can be omitted, for example, you can provide ``Int32Type``
+instead of ``org.apache.cassandra.db.marshal.Int32Type``). See https://github.com/scylladb/scylla/blob/master/docs/design-notes/cql3-type-mapping.md for a mapping of cql3 types to Cassandra type class names.
+
+If you provide more than one value, all of the values must share the same type. For example:
+
+.. code-block:: console
+
+ scylla types print -t Int32Type b34b62d4 00783562
+
+.. _scylla-types-compound:
+
+**Compounds**
+
+A compound is a single value that is composed of multiple values of possibly different types. An example of a compound value is a clustering key or a partition key.
+
+You can use the ``--prefix-compound`` or ``--full-compound`` options to indicate that the provided value is a compound
+(see :ref:`Additional Options <scylla-types-options>`) for details.
+
+When a value is a compound, you can specify a different type for each value making up the compound, **respectively** (i.e., the order
+of the types on the command line must be the same as the order in the compound). For example:
+
+.. code-block:: console
+
+ scylla types print --prefix-compound -t TimeUUIDType -t Int32Type 0010d00819896f6b11ea00000000001c571b000400000010
+
+
+.. _scylla-types-operations:
+
+Supported Operations
+^^^^^^^^^^^^^^^^^^^^^^^
+* ``print`` - Deserializes and prints the provided value in a human-readable form. Required arguments: 1 or more serialized values.
+* ``compare`` - Compares two values and print the result. Required arguments: 2 serialized values.
+* ``validate`` - Verifies if the value is valid for the type, according to the requirements of the type. Required arguments: 1 or more serialized values.
+
+
+.. _scylla-types-options:
+
+Additional Options
+^^^^^^^^^^^^^^^^^^^
+
+You can run ``scylla types [operation] --help`` for additional information on a given operation.
+
+* ``-h`` ( or ``--help``) - Prints the help message.
+* ``--help-seastar`` - Prints the help message about the Seastar options.
+* ``--help-loggers`` - Prints a list of logger names.
+* ``-t`` ( or ``--type``) - Specifies the type of the provided value. See :ref:`Specifying the Value Type <scylla-types-type>`.
+* ``--prefix-compound`` - Indicates that the value is a prefixable compound (e.g., clustering key) composed of multiple values of possibly different types.
+* ``--full-compound`` - Indicates that the value is a full compound (e.g., partition key) composed of multiple values of possibly different types.
+* ``--value arg`` - Specifies the value to process (if not provided as a positional argument).
+
+Examples
+^^^^^^^^
+* Deserializing and printing a value of type Int32Type:
+
+ .. code-block:: console
+
+ scylla types print -t Int32Type b34b62d4
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ -1286905132
+
+* Validating a value of type Int32Type:
+
+ .. code-block:: console
+
+ scylla types validate -t Int32Type b34b62d4
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ b34b62d4: VALID - -1286905132
+
+* Comparing two values of ReversedType(TimeUUIDType):
+
+ .. code-block:: console
+
+ scylla types compare -t 'ReversedType(TimeUUIDType)' b34b62d46a8d11ea0000005000237906 d00819896f6b11ea00000000001c571b
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ b34b62d4-6a8d-11ea-0000-005000237906 > d0081989-6f6b-11ea-0000-0000001c571b
+
+* Deserializing and printing a compound value:
+
+ .. code-block:: console
+
+ scylla types print --prefix-compound -t TimeUUIDType -t Int32Type 0010d00819896f6b11ea00000000001c571b000400000010
+
+ Output:
+
+ .. code-block:: console
+ :class: hide-copy-button
+
+ (d0081989-6f6b-11ea-0000-0000001c571b, 16)
+
diff --git a/docs/operating-scylla/admin-tools/sstable-index.rst b/docs/operating-scylla/admin-tools/sstable-index.rst
--- a/docs/operating-scylla/admin-tools/sstable-index.rst
+++ b/docs/operating-scylla/admin-tools/sstable-index.rst
@@ -0,0 +1,64 @@
+SSTable Index
+=============
+
+.. versionadded:: 4.4 Scylla Open Source
+
+*scylla-sstable-index* is a tool which lists all partitions contained in an SSTable index.
+As all partitions in an SSTable are indexed, this tool can be used to find out
+what partitions are contained in a given SSTable.
+
+The command syntax is as follows:
+
+.. code-block:: none
+
+ ./scylla-sstable-index [--type=<CassandraType>] <--sstable> [path/to/scylla/datadir]
+
+Where:
+
+* The ``--type`` or ``-t`` flag is used to specify the types making up the partition key of the table to which the index file belongs.
+ This is needed so the tool can parse the SSTable keys found in the index. You will need to pass ``--type|-t`` for each type in the partition key.
+ For the type names, the Cassandra type class notation has to be used. You can use the short form, i.e. without the org.apache.cassandra.db.marshal. prefix.
+ For a complete mapping of CQL types to their respective Cassandra type class notation, see `CQL3 Type Mapping <https://scylla.docs.scylladb.com/master/design-notes/cql3-type-mapping.html#cql3-type-mapping>`_.
+
+* The SSTable index file path can be passed both as a positional argument ``[path/to/scylla/datadir]`` or with the ``--sstable`` flag.
+
+The output has the following format:
+
+``$pos: $human_readable_value (pk{$raw_hex_value})``
+
+Where:
+
+* ``$pos:`` the position of the partition in the (decompressed) data file
+* ``$human_readable_value:`` the human readable partition key
+* ``$raw_hex_value:`` the raw hexadecimal value of the binary representation of the partition key
+
+
+Example
+-------
+
+If you have the following schema:
+
+.. code-block:: none
+
+ CREATE TABLE my_keyspace.my_table (
+ id1 int,
+ id2 text,
+ value text,
+ PRIMARY KEY ((id1, id2))
+ );
+
+and you run:
+
+.. code-block:: none
+
+ $ build/dev/tools/scylla-sstable-index --type=Int32Type --type=UTF8Type --sstable /path/to/scylla/datadir/my_keyspace/my_table-1e13d620ea2811ebb808c477e839c4d7/md-1-big-Index.db
+
+the output would be:
+
+.. code-block:: none
+
+ 0: 3:third (pk{00040000000300057468697264})
+ 45: 2:second (pk{00040000000200067365636f6e64})
+ 91: 1:first (pk{00040000000100056669727374})
+
+.. tip:: Using the tool output you can use the raw Hex values to cross reference the :doc:`Scylla Logs </troubleshooting/log-level>` and find information on your SSTable.
\ No newline at end of file
diff --git a/docs/operating-scylla/admin-tools/sstable2json.rst b/docs/operating-scylla/admin-tools/sstable2json.rst
--- a/docs/operating-scylla/admin-tools/sstable2json.rst
+++ b/docs/operating-scylla/admin-tools/sstable2json.rst
@@ -0,0 +1,45 @@
+SSTable2json
+============
+
+
+This tool allows you to converts SSTable into a JSON format file.
+SSTable2json supported when using Scylla 2.x or lower version.
+In newer versions, the tool is named SSTabledump_.
+
+.. _SSTabledump: /operating-scylla/admin-tools/sstabledump
+
+.. note::
+
+ It is not recommended to use this tool in the production cluster.
+
+Use the full path when executing the command.
+
+For example:
+
+.. code-block:: shell
+
+ sstable2json /var/lib/scylla/data/keyspace1/standard1-7119946056b211e98e85000000000001
+
+Example output:
+
+.. code-block:: shell
+
+ [
+ {
+ "partition" : {
+ "key" : [ "3137343334334f4f4d30" ],
+ "position" : 0
+ },
+ "rows" : [
+ {
+ "type" : "static_block",
+ "position" : 281,
+ "cells" : [
+ { "name" : "\"C0\"", "value" : "0xb7789e7cdf2af541061f207714a3b8e14c72f74e663bd5c2577ac329bcb3161cf10c", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C1\"", "value" : "0xe8ed77f078a23e37f8a7246ccd8cd4099585c7031e242529e5070246860d7a1b1e85", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C2\"", "value" : "0x3b836d4333d2d5a02a63ced47596bfb5f80ecb8e80686061c3daaba87380994b7b61", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C3\"", "value" : "0x9220219581df87ff131306b8bf793c14ae8ebf8c8af1b638827ebfcab85660a378b8", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C4\"", "value" : "0x5b4c972cdeb330035b82dc0b1daa9051fff7956d45e3c6c2b21dfb1fd2bb43fb1146", "tstamp" : "2019-04-04T08:22:24.336001Z" }
+ ]
+ }
+ ]
diff --git a/docs/operating-scylla/admin-tools/sstabledump.rst b/docs/operating-scylla/admin-tools/sstabledump.rst
--- a/docs/operating-scylla/admin-tools/sstabledump.rst
+++ b/docs/operating-scylla/admin-tools/sstabledump.rst
@@ -0,0 +1,52 @@
+SSTabledump
+============
+
+This tool allows you to converts SSTable into a JSON format file.
+SSTabledump supported when using Scylla 3.0, Scylla Enterprise 2019.1, and newer versions.
+In older versions, the tool is named SSTable2json_.
+
+.. _SSTable2json: /operating-scylla/admin-tools/sstable2json
+
+Use the full path to the data file when executing the command.
+
+For example:
+
+.. code-block:: shell
+
+ sstabledump /var/lib/scylla/data/keyspace1/standard1-7119946056b211e98e85000000000001/mc-12-big-Data.db
+
+Example output:
+
+.. code-block:: shell
+
+ [
+ {
+ "partition" : {
+ "key" : [ "3137343334334f4f4d30" ],
+ "position" : 0
+ },
+ "rows" : [
+ {
+ "type" : "static_block",
+ "position" : 281,
+ "cells" : [
+ { "name" : "\"C0\"", "value" : "0xb7789e7cdf2af541061f207714a3b8e14c72f74e663bd5c2577ac329bcb3161cf10c", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C1\"", "value" : "0xe8ed77f078a23e37f8a7246ccd8cd4099585c7031e242529e5070246860d7a1b1e85", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C2\"", "value" : "0x3b836d4333d2d5a02a63ced47596bfb5f80ecb8e80686061c3daaba87380994b7b61", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C3\"", "value" : "0x9220219581df87ff131306b8bf793c14ae8ebf8c8af1b638827ebfcab85660a378b8", "tstamp" : "2019-04-04T08:22:24.336001Z" },
+ { "name" : "\"C4\"", "value" : "0x5b4c972cdeb330035b82dc0b1daa9051fff7956d45e3c6c2b21dfb1fd2bb43fb1146", "tstamp" : "2019-04-04T08:22:24.336001Z" }
+ ]
+ }
+ ]
+
+
+
+**NOTE:**
+
+When running as a user that is not ``root`` or ``scylla`` an error (java traceback) might be observed.
+To work around the error, please use the following syntax:
+
+.. code-block:: sh
+
+ cassandra_storagedir="/tmp" sstabledump [filename]
+
diff --git a/docs/operating-scylla/admin-tools/sstableloader.rst b/docs/operating-scylla/admin-tools/sstableloader.rst
--- a/docs/operating-scylla/admin-tools/sstableloader.rst
+++ b/docs/operating-scylla/admin-tools/sstableloader.rst
@@ -0,0 +1,58 @@
+SSTableLoader
+=============
+
+Bulk load the sstables from a directory to a Scylla cluster via the **CQL API**.
+
+.. note::
+
+ This is **different** than Apache Cassandra tool with the same name, which uses internal RPC protocol to load the data.
+
+.. note::
+
+ sstableloader does **not** support loading from encrypted files. For restoring data from encrypted files see :ref:`Migration to Scylla <cassandra-to-scylla-procedure>`.
+
+
+SSTableLoader can be used to restore data from Scylla or Apache Cassandra backups or to clone data from cluster to cluster.
+It is especially useful, when the number of nodes, or token range distrbution between the source and target cluster are **not** the same. Since CQL API is used, Scylla will take care of distrbution the data.
+
+For example of such usage see :doc:`Apache Cassandra to Scylla Migration Process </operating-scylla/procedures/cassandra-to-scylla-migration-process>`
+
+usage: sstableloader [options] <dir_path>
+
+Bulk load the sstables found in the directory <dir_path> to the configured cluster. The parent directories of <dir_path> are used as the target ``keyspace/table`` name. So, for instance, to load an sstable named ``Standard1-g-1-Data.db`` into ``Keyspace1/Standard1``, you will need to have the files ``Standard1-g-1-Data.db`` and ``Standard1-g-1-Index.db`` into a directory ``/path/to/Keyspace1/Standard1/``.
+
+Parameters:
+
+* ``-alg,--ssl-alg <ALGORITHM>`` - Client SSL: algorithm (default: SunX509)
+* ``-bs,--batch-size <Number of bytes above which batch is being sent out>`` - Does not work with ``-nb``
+* ``-ciphers,--ssl-ciphers <CIPHER-SUITES>`` - Client SSL: comma-separated list of encryption suites to use
+* ``-cl,--consistency-level <consistency level (default: ONE)>`` - sets the consistency level for statements
+* ``-cph,--connections-per-host <connectionsPerHost>`` - number of concurrent connections-per-host.
+* ``-d,--nodes <initial hosts>`` - Required. try to connect to these hosts (comma separated) initially for ring information
+* ``-f,--conf-path <path to config file>`` - cassandra.yaml file path for streaming throughput and client/server SSL.
+* ``-g,--ignore-missing-columns <COLUMN NAMES...>`` - ignore named missing columns in tables
+* ``-h,--help`` - display this help message
+* ``-i,--ignore <NODES>`` - don't stream to this (comma separated) list of nodes
+* ``-ic,--ignore-dropped-counter-data`` - ignore dropping local and remote counter shard data
+* ``-ir,--no-infinite-retry`` - Disable infinite retry policy
+* ``-j,--threads-count <Number of threads to execute tasks>`` - Run tasks in parallel
+* ``-ks,--keystore <KEYSTORE>`` - Client SSL: full path to keystore
+* ``-kspw,--keystore-password <KEYSTORE-PASSWORD>`` - Client SSL: password of the keystore
+* ``-nb,--no-batch`` - Do not use batch statements updates for same partition key.
+* ``--no-progress`` - don't display progress
+* ``-nx,--no-prepared`` - Do not use prepared statements
+* ``-p,--port <port>`` - port used for connections (default 9042)
+* ``-prtcl,--ssl-protocol <PROTOCOL>`` - Client SSL: connections protocol to use (default: TLS)
+* ``-pt,--partitioner <class>`` - Partitioner type to use, defaults to cluster value
+* ``-pw,--password <password>`` - password for cassandra authentication
+* ``-s,--ssl <SSL>`` - Use SSL connection(s)
+* ``-sim,--simulate`` - simulate. Only print CQL generated
+* ``-st,--store-type <STORE-TYPE>`` - Client SSL: type of store
+* ``-t,--throttle <throttle>`` - throttle speed in Mbits (default unlimited)
+* ``-tr,--token-ranges <<lo>:<hi>,...>`` - import only partitions that satisfy lo < token(partition) <= hi
+* ``-translate,--translate <mapping list>`` - comma-separated list of column name mappings
+* ``-ts,--truststore <TRUSTSTORE>`` - Client SSL: full path to truststore
+* ``-tspw,--truststore-password <TRUSTSTORE-PASSWORD>`` - Client SSL: password of the truststore
+* ``--use-unset`` - Use 'unset' values in prepared statements
+* ``--username <username>`` - username for cassandra authentication
+* ``-v,--verbose <LEVEL>`` - verbose output
diff --git a/docs/operating-scylla/admin-tools/virtual-tables.rst b/docs/operating-scylla/admin-tools/virtual-tables.rst
--- a/docs/operating-scylla/admin-tools/virtual-tables.rst
+++ b/docs/operating-scylla/admin-tools/virtual-tables.rst
@@ -0,0 +1,15 @@
+===============
+Virtual Tables
+===============
+
+Virtual tables expose system-level information in the familiar CQL or Alternator interfaces.
+Virtual tables are not backed by physical storage (sstables) and generate their content on-the-fly when
+queried.
+
+ScyllaDB supports:
+
+* Virtual tables for retrieving system-level information, such as the cluster status, version-related information, etc. The range of information they can expose partially overlaps with the information you can obtain via :doc:`nodetool </operating-scylla/nodetool>` (unlike ``nodetool``, virtual tables permit remote access over CQL).
+* The virtual table for querying and updating configuration over CQL (the ``system.config`` table).
+
+See `Virtual tables in the system keyspace <https://github.com/scylladb/scylla/blob/branch-5.0/docs/design-notes/system_keyspace.md#virtual-tables-in-the-system-keyspace>`_ for the list of available virtual tables.
+
diff --git a/docs/operating-scylla/admin.rst b/docs/operating-scylla/admin.rst
--- a/docs/operating-scylla/admin.rst
+++ b/docs/operating-scylla/admin.rst
@@ -0,0 +1,273 @@
+Administration Guide
+********************
+
+For training material, also check out the `Admin Procedures lesson <https://university.scylladb.com/courses/scylla-operations/lessons/admin-procedures-and-basic-monitoring/>`_ on Scylla University.
+
+System requirements
+===================
+Make sure you have met the :doc:`System Requirements </getting-started/system-requirements>` before you install and configure Scylla.
+
+Download and Install
+====================
+
+See the :doc:`getting started page </getting-started/index>` for info on installing Scylla on your platform.
+
+
+System configuration
+====================
+See :ref:`System Configuration Guide <system-configuration-files-and-scripts>` for details on optimum OS settings for Scylla. (These settings are performed automatically in the Scylla packages, Docker containers, and Amazon AMIs.)
+
+.. _admin-scylla-configuration:
+
+Scylla Configuration
+====================
+Scylla configuration files are:
+
++-------------------------------------------------------+---------------------------------+
+| Installed location | Description |
++=======================================================+=================================+
+| :code:`/etc/default/scylla-server` (Ubuntu/Debian) | Server startup options |
+| :code:`/etc/sysconfig/scylla-server` (others) | |
++-------------------------------------------------------+---------------------------------+
+| :code:`/etc/scylla/scylla.yaml` | Main Scylla configuration file |
++-------------------------------------------------------+---------------------------------+
+| :code:`/etc/scylla/cassandra-rackdc.properties` | Rack & dc configuration file |
++-------------------------------------------------------+---------------------------------+
+
+.. _check-your-current-version-of-scylla:
+
+Check your current version of Scylla
+------------------------------------
+This command allows you to check your current version of Scylla. Note that this command is not the :doc:`nodetool version </operating-scylla/nodetool-commands/version>` command which reports the CQL version.
+If you are looking for the CQL or Cassandra version, refer to the CQLSH reference for :ref:`SHOW VERSION <cqlsh-show-version>`.
+
+.. code-block:: shell
+
+ scylla --version
+
+Output displays the Scylla version. Your results may differ.
+
+.. code-block:: shell
+
+ 4.4.0-0.20210331.05c6a40f0
+
+.. _admin-address-configuration-in-scylla:
+
+Address Configuration in Scylla
+-------------------------------
+
+The following addresses can be configured in scylla.yaml:
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Address Type
+ - Description
+ * - listen_address
+ - Address Scylla listens for connections from other nodes. See storage_port and ssl_storage_ports.
+ * - rpc_address
+ - Address on which Scylla is going to expect Thrift and CQL client connections. See rpc_port, native_transport_port and native_transport_port_ssl in the :ref:`Networking <cqlsh-networking>` parameters.
+ * - broadcast_address
+ - Address that is broadcasted to tell other Scylla nodes to connect to. Related to listen_address above.
+ * - broadcast_rpc_address
+ - Address that is broadcasted to tell the clients to connect to. Related to rpc_address.
+ * - seeds
+ - The broadcast_addresses of the existing nodes. You must specify the address of at least one existing node.
+ * - endpoint_snitch
+ - Node's address resolution helper.
+ * - api_address
+ - Address for REST API requests. See api_port in the :ref:`Networking <cqlsh-networking>` parameters.
+ * - prometheus_address
+ - Address for Prometheus queries. See prometheus_port in the :ref:`Networking <cqlsh-networking>` parameters and :doc:`Scylla Monitoring </operating-scylla/monitoring/index>` for more details.
+ * - replace_address_first_boot
+ - Address of the node this Scylla instance is meant to replace. Refer to :doc:`Replace a Dead Node in a Scylla Cluster </operating-scylla/procedures/cluster-management/replace-dead-node>` for more details.
+
+.. note:: When the listen_address, rpc_address, broadcast_address, and broadcast_rpc_address parameters are not set correctly, Scylla does not work as expected.
+
+scylla-server
+-------------
+The :code:`scylla-server` file contains configuration related to starting up the Scylla server.
+
+.. include:: /operating-scylla/scylla-yaml.inc
+
+Compression
+-----------
+
+In Scylla, you can configure compression at rest and compression in transit.
+For compression in transit, you can configure compression between nodes or between the client and the node.
+
+Client - Node Compression
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Compression between the client and the node is set by the driver that the application is using to access Scylla.
+
+For example:
+
+* `Scylla Python Driver <https://scylladb.github.io/python-driver/master/api/cassandra/cluster.html#cassandra.cluster.Cluster.compression>`_
+* `Scylla Java Driver <https://github.com/scylladb/java-driver/tree/3.7.1-scylla/manual/compression>`_
+* `Go Driver <https://godoc.org/github.com/gocql/gocql#Compressor>`_
+
+Refer to the :doc:`Drivers Page </using-scylla/drivers/index>` for more drivers.
+
+.. _internode-compression:
+
+Internode Compression
+^^^^^^^^^^^^^^^^^^^^^
+
+Internode compression is configured in the scylla.yaml
+
+internode_compression controls whether traffic between nodes is compressed.
+
+* all - all traffic is compressed.
+* dc - traffic between different datacenters is compressed.
+* none - nothing is compressed (default).
+
+Configuring TLS/SSL in scylla.yaml
+----------------------------------
+
+Scylla versions 1.1 and greater support encryption between nodes and between client and node. See the Scylla :doc:`Scylla TLS/SSL guide: </operating-scylla/security/index>` for configuration settings.
+
+.. _cqlsh-networking:
+
+Networking
+----------
+
+.. include:: /operating-scylla/_common/networking-ports.rst
+
+.. image:: /operating-scylla/security/Scylla-Ports2.png
+
+The Scylla ports are detailed in the table below. For Scylla Manager ports, see the `Scylla Manager Documentation <https://scylladb.github.io/scylla-manager>`_.
+
+.. include:: /operating-scylla/_common/networking-ports.rst
+
+All ports above need to be open to external clients (CQL), external admin systems (JMX), and other nodes (RPC). REST API port can be kept closed for incoming external connections.
+
+The JMX service, :code:`scylla-jmx`, runs on port 7199. It is required in order to manage Scylla using :code:`nodetool` and other Apache Cassandra-compatible utilities. The :code:`scylla-jmx` process must be able to connect to port 10000 on localhost. The JMX service listens for incoming JMX connections on all network interfaces on the system.
+
+Advanced networking
+-------------------
+It is possible that a client, or another node, may need to use a different IP address to connect to a Scylla node from the address that the node is listening on. This is the case when a node is behind port forwarding. Scylla allows for setting alternate IP addresses.
+
+Do not set any IP address to :code:`0.0.0.0`.
+
+.. list-table::
+ :widths: 30 40 30
+ :header-rows: 1
+
+ * - Address Type
+ - Description
+ - Default
+ * - listen_address (required)
+ - Address Scylla listens for connections from other nodes. See storage_port and ssl_storage_ports.
+ - No default
+ * - rpc_address (required)
+ - Address on which Scylla is going to expect Thrift and CQL clients connections. See rpc_port, native_transport_port and native_transport_port_ssl in the :ref:`Networking <cqlsh-networking>` parameters.
+ - No default
+ * - broadcast_address
+ - Address that is broadcasted to tell other Scylla nodes to connect to. Related to listen_address above.
+ - listen_address
+ * - broadcast_rpc_address
+ - Address that is broadcasted to tell the clients to connect to. Related to rpc_address.
+ - rpc_address
+
+
+If other nodes can connect directly to :code:`listen_address`, then :code:`broadcast_address` does not need to be set.
+
+If clients can connect directly to :code:`rpc_address`, then :code:`broadcast_rpc_address` does not need to be set.
+
+.. note:: For tips and examples on how to configure these addresses, refer to :doc:`How to Properly Set Address Values in scylla.yaml </kb/yaml-address>`
+
+.. _admin-core-dumps:
+
+Core dumps
+----------
+On RHEL and CentOS, the Automatic Bug Reporting Tool (`ABRT <https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/System_Administrators_Guide/ch-abrt.html>`_) conflicts with Scylla coredump configuration. Remove it before installing Scylla: :code:`sudo yum remove -y abrt`
+
+Scylla places any core dumps in :code:`var/lib/scylla/coredump`. They are not visible with the :code:`coredumpctl` command. See the :doc:`System Configuration Guide </getting-started/system-configuration/>` for details on core dump configuration scripts. Check with Scylla support before sharing any core dump, as they may contain sensitive data.
+
+
+Manual bootstrapping
+====================
+It’s possible to skip the bootstrapping process entirely and join the ring straight away by setting the hidden parameter ``auto_bootstrap: false``.
+A manual bootstrap node will skip the data stream phase and immediately join the cluster in a *UN* (Up Normal) state and start serving queries, even though it has no data.
+**It is firmly advised not to use Manual bootstrapping.**
+
+Note that starting a node as a seed, by including itself in the seeds list, has a similar effect of and it is similarly dangerous.
+
+See :doc:`Node Joined With No Data </troubleshooting/node-joined-without-any-data>` for troubleshooting a manually bootstrap node.
+
+Schedule fstrim
+===============
+
+Scylla sets up daily fstrim on the filesystem(s),
+containing your Scylla commitlog and data directory. This utility will
+discard, or trim, any blocks no longer in use by the filesystem.
+
+Experimental Features
+=====================
+
+Scylla Open Source uses experimental flags to expose non-production-ready features safely. These features are not stable enough to be used in production, and their API will likely change, breaking backward or forward compatibility.
+
+In recent Scylla versions, these features are controlled by the ``experimental_features`` list in scylla.yaml, allowing one to choose which experimental to enable.
+For example, some of the experimental features in Scylla Open Source 4.5 are: ``udf``, ``alternator-streams`` and ``raft``.
+Use ``scylla --help`` to get the list of experimental features.
+
+Scylla Enterprise and Scylla Cloud do not officially support experimental Features.
+
+Monitoring
+==========
+Scylla exposes interfaces for online monitoring, as described below.
+
+Monitoring Interfaces
+---------------------
+
+`Scylla Monitoring Interfaces <https://monitoring.docs.scylladb.com/stable/reference/monitoring_apis.html>`_
+
+Monitoring Stack
+----------------
+
+|mon_root|
+
+JMX
+---
+Scylla JMX is compatible with Apache Cassandra, exposing the relevant subset of MBeans.
+
+.. REST
+
+.. include:: /operating-scylla/rest.rst
+
+Un-contents
+-----------
+
+Scylla is designed for high performance before tuning, for fewer layers that interact in unpredictable ways, and to use better algorithms that do not require manual tuning. The following items are found in the manuals for other data stores but do not need to appear here.
+
+Configuration un-contents
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Generating tokens
+* Configuring virtual nodes
+
+Operations un-contents
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Tuning Bloom filters
+* Data caching
+* Configuring memtable throughput
+* Configuring compaction
+* Compression
+
+Testing compaction and compression
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Tuning Java resources
+* Purging gossip state on a node
+
+
+Help with Scylla
+================
+Contact `Support <https://www.scylladb.com/product/support/>`_, or visit the Scylla `Community <https://www.scylladb.com/open-source-community/>`_ page for peer support.
+
+.. include:: /rst_include/apache-copyrights-index.rst
+
+.. include:: /rst_include/apache-copyrights-index-all-attributes.rst
diff --git a/docs/operating-scylla/benchmarking-scylla.rst b/docs/operating-scylla/benchmarking-scylla.rst
--- a/docs/operating-scylla/benchmarking-scylla.rst
+++ b/docs/operating-scylla/benchmarking-scylla.rst
@@ -0,0 +1,9 @@
+===================
+Benchmarking Scylla
+===================
+
+
+For more information on the best way to benchmark Scylla, check out our blog:
+
+* `Best Practices for Benchmarking Scylla <https://www.scylladb.com/2021/03/04/best-practices-for-benchmarking-scylla/>`_
+* `How to Test and Benchmark Database Clusters <https://www.scylladb.com/2020/11/04/how-to-test-and-benchmark-database-clusters/>`_
diff --git a/docs/operating-scylla/gcsnitch.png b/docs/operating-scylla/gcsnitch.png
--- a/docs/operating-scylla/gcsnitch.png
+++ b/docs/operating-scylla/gcsnitch.png
null
diff --git a/docs/operating-scylla/index.rst b/docs/operating-scylla/index.rst
--- a/docs/operating-scylla/index.rst
+++ b/docs/operating-scylla/index.rst
@@ -0,0 +1,57 @@
+Scylla for Administrators
+=========================
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ admin
+ Procedures <procedures/index>
+ security/index
+ admin-tools/index
+ manager/index
+ Scylla Monitoring Stack <monitoring/index>
+ Scylla Operator <scylla-operator/index>
+ Upgrade Procedures </upgrade/index>
+ System Configuration <system-configuration/index>
+ benchmarking-scylla
+
+.. panel-box::
+ :title: Scylla Administration
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Administrator Guide </operating-scylla/admin/>` - Guide for Scylla Administration
+ * :doc:`Upgrade Scylla </upgrade/index>` - Upgrade Procedures for all Scylla Products and Versions
+ * :doc:`System Configuration </operating-scylla/system-configuration/index>` - Information on the Scylla configuration files
+ * :doc:`Procedures </operating-scylla/procedures/index>` - Procedures to create, out-scale, down-scale, and backup Scylla clusters
+ * :doc:`Scylla Security </operating-scylla/security/index>` - Procedures to secure, authenticate, and encrypt Scylla users and data
+
+.. panel-box::
+ :title: Scylla Tools
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Scylla Tools </operating-scylla/admin-tools/index>` - Tools for Administrating and integrating with Scylla
+ * :doc:`Scylla Manager </operating-scylla/manager/index>` - Tool for cluster administration and automation
+ * :doc:`Scylla Monitoring Stack </operating-scylla/monitoring/index>` - Tool for cluster monitoring and alerting
+ * :doc:`Scylla Operator </operating-scylla/scylla-operator/index>` - Tool to run Scylla on Kubernetes
+ * :doc:`Scylla Logs </getting-started/logging/>`
+
+.. panel-box::
+ :title: Benchmark Testing
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Benchmark Testing for Scylla </operating-scylla/benchmarking-scylla/>` - Information on benchmark tests you can conduct on Scylla
+
+.. panel-box::
+ :title: Learn More About Scylla
+ :id: "getting-started"
+ :class: my-panel
+
+ * :doc:`Learn To Use Scylla </using-scylla/learn>` - Scylla University offers many courses. Pick a course and get started on your path to becoming a Scylla expert.
+ * :doc:`Scylla Features </using-scylla/features>` - Feature list for Scylla Open Source and Scylla Enterprise
+
+
+
diff --git a/docs/operating-scylla/manager/2.1/_common/cluster-params.rst b/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
--- a/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
+++ b/docs/operating-scylla/manager/2.1/_common/cluster-params.rst
@@ -0,0 +1,40 @@
+``--host <node IP>``
+
+Specifies the hostname or IP of the node that will be used to discover other nodes belonging to the cluster.
+Note that this will be persisted and used every time Scylla Manager starts. You can use either an IPv4 or IPv6 address.
+
+=====
+
+``-n, --name <alias>``
+
+When a cluster is added, it is assigned a unique identifier.
+Use this parameter to identify the cluster by an alias name which is more meaningful.
+This alias name can be used with all commands that accept ``-c, --cluster`` parameter.
+
+=====
+
+``--auth-token <token>``
+
+Specifies the :ref:`authentication token <manager-2.1-generate-auth-token>` you identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+=====
+
+``-u, --username <cql username>``
+
+Optional CQL username, for security reasons this user should NOT have access to your data.
+If you specify the CQL username and password, the CQL health check you see in `status`_ would try to login and execute a query against system keyspace.
+Otherwise CQL health check is based on sending `CQL OPTIONS frame <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec#L302>`_ and does not start a CQL session.
+
+=====
+
+``-p, --password <password>``
+
+CQL password associated with username.
+
+=====
+
+``--without-repair``
+
+When cluster is added, Manager schedules repair to repeat every 7 days. To create a cluster without a scheduled repair, use this flag.
+
+
diff --git a/docs/operating-scylla/manager/2.1/_common/glob.rst b/docs/operating-scylla/manager/2.1/_common/glob.rst
--- a/docs/operating-scylla/manager/2.1/_common/glob.rst
+++ b/docs/operating-scylla/manager/2.1/_common/glob.rst
@@ -0,0 +1,10 @@
+The following syntax is supported:
+
+* ``*`` - matches any number of any characters including none
+* ``?`` - matches any single character
+* ``[abc]`` - matches one character given in the bracket
+* ``[a-z]`` - matches one character from the range given in the bracket
+
+Patterns are evaluated from left to right.
+If a pattern starts with ``!`` it unselects items that were selected by previous patterns
+i.e. ``a?,!aa`` selects *ab* but not *aa*.
diff --git a/docs/operating-scylla/manager/2.1/_common/manager-description.rst b/docs/operating-scylla/manager/2.1/_common/manager-description.rst
--- a/docs/operating-scylla/manager/2.1/_common/manager-description.rst
+++ b/docs/operating-scylla/manager/2.1/_common/manager-description.rst
@@ -0,0 +1,6 @@
+Scylla Manager is a product for database operations automation, it can schedule tasks such as repairs and backups.
+Scylla Manager can manage multiple Scylla clusters and run cluster-wide tasks in a controlled and predictable way.
+
+Scylla Manager is available for Scylla Enterprise customers and Scylla Open Source users.
+With Scylla Open Source, Scylla Manager is limited to 5 nodes.
+See the Scylla Manager Proprietary Software `License Agreement <https://www.scylladb.com/scylla-manager-software-license-agreement/>`_ for details.
diff --git a/docs/operating-scylla/manager/2.1/_common/param-cluster.rst b/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
--- a/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
+++ b/docs/operating-scylla/manager/2.1/_common/param-cluster.rst
@@ -0,0 +1,3 @@
+``-c`` , ``--cluster``
+
+This is the cluster name is the name you assigned when you created the cluster (`cluster add`_). You can see the cluster name and ID by running the command `cluster list`_.
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/2.1/_common/task-id-note.rst b/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
--- a/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
+++ b/docs/operating-scylla/manager/2.1/_common/task-id-note.rst
@@ -0,0 +1,3 @@
+A task ID with a type (repair, for example) is **required** for this command.
+This is a unique ID which is created when the task was made.
+To display the ID, run the command ``sctool task list`` (see `task list`_).
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/2.1/_common/task-params.rst b/docs/operating-scylla/manager/2.1/_common/task-params.rst
--- a/docs/operating-scylla/manager/2.1/_common/task-params.rst
+++ b/docs/operating-scylla/manager/2.1/_common/task-params.rst
@@ -0,0 +1,41 @@
+``--interval <time between task runs>``
+
+Amount of time after which a successfully completed task would be run again.
+Supported time units include:
+
+* ``d`` - days,
+* ``h`` - hours,
+* ``m`` - minutes,
+* ``s`` - seconds.
+
+**Default** 0 (no interval)
+
+.. note:: The task run date is aligned with ``--start date`` value. For example, if you select ``--interval 7d`` task would run weekly at the ``--start-date`` time.
+
+=====
+
+``-s, --start-date <now+duration|RFC3339>``
+
+The date can be expressed relatively to now or as a RFC3339 formatted string.
+To run the task in 2 hours use ``now+2h``, supported units are:
+
+* ``h`` - hours,
+* ``m`` - minutes,
+* ``s`` - seconds,
+* ``ms`` - milliseconds.
+
+If you want the task to start at a specified date use RFC3339 formatted string i.e. ``2018-01-02T15:04:05-07:00``.
+If you want the repair to start immediately, use the value ``now`` or skip this flag.
+
+**Default:** now (start immediately)
+
+=====
+
+``-r, --num-retries <times to rerun a failed task>``
+
+Number of times a task reruns following a failure. The task reruns 10 minutes following a failure.
+If the task fails after the retry times have been used, it will not retry again until its next run which was scheduled according to the ``--interval`` parameter.
+
+.. note:: If this is an ad hoc repair, the task will not run again.
+
+**Default:** 3
diff --git a/docs/operating-scylla/manager/2.1/add-a-cluster.rst b/docs/operating-scylla/manager/2.1/add-a-cluster.rst
--- a/docs/operating-scylla/manager/2.1/add-a-cluster.rst
+++ b/docs/operating-scylla/manager/2.1/add-a-cluster.rst
@@ -0,0 +1,162 @@
+=========================================
+Add a cluster or a node to Scylla Manager
+=========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+Scylla Manager manages clusters. A cluster contains one or more nodes / datacenters. When you add a cluster to Scylla Manager, it adds all of the nodes which are:
+
+* associated with it,
+* that are running Scylla Manager Agent,
+* and are accessible
+
+
+Port Settings
+=============
+
+Confirm all ports required for Scylla Manager and Scylla Manager Agent are open. This includes:
+
+* 9042 CQL
+* 9142 SSL CQL
+* 10001 Scylla Agent REST API
+
+
+Add a Cluster
+=============
+
+This procedure adds the nodes to Scylla Manager so the cluster can be a managed cluster under Scylla Manager.
+
+Prerequisites
+-------------
+
+For each node in the cluster, the **same** :ref:`authentication token <manager-2.1-generate-auth-token>` needs to be identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+Create a Managed Cluster
+------------------------
+
+.. _name:
+
+**Procedure**
+
+#. From the Scylla Manager Server, provide the broadcast_address of one of the nodes and the generated auth_token (if used) and a custom name if desired.
+
+ Where:
+
+ * ``--host`` is hostname or IP of one of the cluster nodes. You can use an IPv6 or an IPv4 address.
+ * ``--name`` is an alias you can give to your cluster. Using an alias means you do not need to use the ID of the cluster in all other operations.
+ * ``--auth-token`` is the authentication :ref:`token <manager-2.1-generate-auth-token>` you identified in ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+ * ``--without-repair`` - when a cluster is added, the Manager schedules repair to repeat every 7 days. To create a cluster without a scheduled repair, use this flag.
+ * ``--username`` and ``--password`` - optionally, you can provide CQL credentials to the cluster.
+ For security reasons, the user should NOT have access to your data.
+ This enables :ref:`CQL query-based health check <manager-2.1-cql-query-health-check>` compared to :ref:`credentials agnostic health check <manager-2.1-credentials-agnostic-health-check>` if you do not specify the credentials.
+ This also enables CQL schema backup, which isn't performed if credentials aren't provided.
+
+ Example (IPv4):
+
+ .. code-block:: none
+
+ sctool cluster add --host 34.203.122.52 --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+ c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ __
+ / \ Cluster added! You can set it as default by exporting env variable.
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ | | $ export SCYLLA_MANAGER_CLUSTER=prod-cluster
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c prod-cluster
+ \___/ $ sctool task list -c prod-cluster
+
+
+ Example (IPv6):
+
+ .. code-block:: none
+
+ sctool cluster add --host 2a05:d018:223:f00:971d:14af:6418:fe2d --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+ Each cluster has a unique ID.
+ You will use this ID in all commands where the cluster ID is required.
+ Each cluster is automatically registered with a repair task that runs once a week.
+ This can be canceled using ``--without-repair``.
+ To use a different repair schedule, see :ref:`Schedule a Repair <manager-2.1-schedule-a-repair>`.
+
+#. Verify that the cluster you added has a registered repair task by running the ``sctool task list -c <cluster-name>`` command, adding the name_ of the cluster you created in step 1 (with the ``--name`` flag).
+
+ .. code-block:: none
+
+ sctool task list -c prod-cluster
+ ╭───────────────────────────────────────────────────────┬───────────┬────────────────────────────────┬────────╮
+ │ Task │ Arguments │ Next run │ Status │
+ ├───────────────────────────────────────────────────────┼───────────┼────────────────────────────────┼────────┤
+ │ healthcheck/8988932e-de2f-4c42-a2f8-ae3b97fd7126 │ │ 02 Apr 20 12:28:10 CEST (+15s) │ NEW │
+ │ healthcheck_rest/9b7e694d-a1e3-42f1-8ca6-d3dfd9f0d94f │ │ 02 Apr 20 12:28:40 CEST (+1h) │ NEW │
+ │ repair/0fd8a43b-eacf-4df8-9376-2a31b0dee6cc │ │ 03 Apr 20 00:00:00 CEST (+7d) │ NEW │
+ ╰───────────────────────────────────────────────────────┴───────────┴────────────────────────────────┴────────╯
+
+ You will see 3 tasks which are created by adding the cluster:
+
+ * Healthcheck - which checks the Scylla CQL, starting immediately, repeating every 15 seconds. See `Scylla Health Check <../health-check>`_
+ * Healthcheck REST - which checks the Scylla REST API, starting immediately, repeating every hour. See `Scylla Health Check <../health-check>`_
+ * Repair - an automated repair task, starting at midnight tonight, repeating every seven days at midnight. See `Run a Repair <../repair/>`_
+
+ .. note:: If you want to change the schedule for the repair, see :ref:`Reschedule a repair <manager-2.1-reschedule-a-repair>`.
+
+Connect Managed Cluster to Scylla Monitoring
+============================================
+
+Connecting your cluster to Scylla Monitoring allows you to see metrics about your cluster and Scylla Manager all within Scylla Monitoring.
+
+To connect your cluster to Scylla Monitoring, it is **required** to use the same cluster name_ as you used when you created the cluster. See `Add a Cluster`_.
+
+**Procedure**
+
+Follow the procedure |mon_root| as directed, remembering to update the Scylla Node IPs and Cluster name_ as well as the Scylla Manager IP in the relevant Prometheus configuration files.
+
+If you have any issues connecting to Scylla Monitoring Stack, consult the :doc:`Troubleshooting Guide </troubleshooting/manager-monitoring-integration>`.
+
+Add a Node to a Managed Cluster
+===============================
+
+Although Scylla Manager is aware of all topology changes made within every cluster it manages, it cannot properly manage nodes/datacenters without establishing connections with every node/datacenter in the cluster, including the Scylla Manager Agent, which is on each managed node.
+
+**Before You Begin**
+
+* Confirm you have a managed cluster running under Scylla Manager. If you do not have a managed cluster, see `Add a cluster`_.
+* Confirm the :ref:`node <add-node-to-cluster-procedure>` or :doc:`Datacenter </operating-scylla/procedures/cluster-management/add-dc-to-existing-dc>` is added to the Scylla Cluster.
+
+**Procedure**
+
+#. `Add Scylla Manager Agent <../install-agent>`_ to the new node. Use the **same** authentication token as you did for the other nodes in this cluster. Do not generate a new token.
+
+#. Confirm the node / datacenter was added by checking its :ref:`status <sctool_status>`. From the node running the Scylla Manager server, run the ``sctool status`` command, using the name of the managed cluster.
+
+ .. code-block:: none
+
+ sctool status -c prod-cluster
+ Datacenter: eu-west
+ ╭────┬───────────────┬────────────┬──────────────┬──────────────────────────────────────╮
+ │ │ CQL │ REST │ Host │ Host ID │
+ ├────┼───────────────┼────────────┼──────────────┼──────────────────────────────────────┤
+ │ UN │ UP SSL (42ms) │ UP (52ms) │ 10.0.114.68 │ 45a7390d-d162-4daa-8bff-6469c9956f8b │
+ │ UN │ UP SSL (38ms) │ UP (88ms) │ 10.0.138.46 │ 8dad7fc7-5a82-4fbb-8901-f6f60c12342a │
+ │ UN │ UP SSL (38ms) │ UP (298ms) │ 10.0.196.204 │ 44eebe5b-e0cb-4e45-961f-4ad175592977 │
+ │ UN │ UP SSL (43ms) │ UP (159ms) │ 10.0.66.115 │ 918a52aa-cc42-43a4-a499-f7b1ccb53b18 │
+ ╰────┴───────────────┴────────────┴──────────────┴──────────────────────────────────────╯
+
+#. If you are using the Scylla Monitoring Stack, continue to `Connect Managed Cluster to Scylla Monitoring`_ for more information.
+
+Remove a Node/Datacenter from Scylla Manager
+--------------------------------------------
+
+There is no need to perform any action in Scylla Manager after removing a node or datacenter from a Scylla cluster.
+
+.. note:: If you are removing the cluster from Scylla Manager and you are using Scylla Monitoring, refer to |mon_root| for more information.
+
+See Also
+========
+
+* `sctool Reference <../sctool>`_
+* :doc:`Remove a node from a Scylla Cluster </operating-scylla/procedures/cluster-management/remove-node>`
+* :doc:`Scylla Monitoring </operating-scylla/monitoring/index>`
+
diff --git a/docs/operating-scylla/manager/2.1/agent-configuration-file.rst b/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
--- a/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
+++ b/docs/operating-scylla/manager/2.1/agent-configuration-file.rst
@@ -0,0 +1,205 @@
+========================
+Agent Configuration File
+========================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+
+This document covers the configurations settings you need to consider for the Sylla Manager Agent.
+
+The Scylla Manager Agent has a single configuration file /etc/scylla-manager-agent/scylla-manager-agent.yaml.
+
+.. _manger-2.1-agent-configuration-file-auth-token:
+
+Authentication token
+====================
+
+.. note:: Completing this section in the scylla-manager-agent.yaml file is mandatory
+
+Scylla Agent uses token authentication in API calls so that the Scylla Manager Server can authenticate itself with the Scylla Manager Agent.
+Once you have :ref:`created a token <manager-2.1-generate-auth-token>`, and have configured the :ref:`agent configuration file <manager-2.1-configure-auth-token>` as described.
+
+.. code-block:: none
+
+ # Specify authentication token
+ auth_token: 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+HTTPS server settings
+=====================
+
+In this section, you can specify which address Scylla Agent should listen to.
+By default, Scylla Manager Agent pulls these values from the Scylla itself.
+Port 10001 is the default port, and traffic to this port should be allowed on the firewall.
+You can change the port to a different port by clearing the ``https`` label and adding an IP address and port.
+In order to obtain TLS cert and key file, use the ``scyllamgr_ssl_cert_gen`` script.
+
+.. code-block:: none
+
+ # Bind REST API to the specified TCP address using HTTPS protocol. By default
+ # Scylla Manager Agent uses Scylla listen/broadcast address that is read from
+ # the Scylla API (see the scylla section).
+ #https: 0.0.0.0:10001
+
+ # TLS certificate and key files to use with HTTPS. To regenerate the files use
+ # scyllamgr_ssl_cert_gen script shipped with the Scylla Manager Agent.
+ #tls_cert_file: /var/lib/scylla-manager/scylla_manager.crt
+ #tls_key_file: /var/lib/scylla-manager/scylla_manager.key
+
+Prometheus settings
+===================
+
+In this section, you can set the Prometheus settings for the Scylla Manager Agent so that the Agent Manager metrics (from each Sylla node) can be viewed and monitored with Scylla Monitoring.
+
+.. code-block:: none
+
+ # Bind Prometheus API to the specified TCP address using HTTP protocol.
+ # By default it binds to all network interfaces, but you can restrict it
+ # by specifying it like this 127:0.0.1:56090 or any other combination
+ # of ip and port.
+ #prometheus: ':56090'
+
+If you change the Prometheus IP or port, you must adjust the rules in the Prometheus server.
+
+.. code-block:: none
+
+ - targets:
+ - IP:56090
+
+Debug endpoint settings
+=======================
+
+In this section, you can specify the pprof debug server address.
+It allows you to run profiling on demand on a live application.
+By default, the server is running on port ``56112``.
+
+.. code-block:: none
+
+ debug: 127.0.0.1:56112
+
+CPU pinning settings
+====================
+
+In this section, you can set the ``cpu`` setting, which dictates the CPU to run Scylla Manager Agent on.
+By default, the agent reads the Scylla configuration from ``/etc/scylla.d/cpuset.conf`` and tries to find a core that is not used by Scylla.
+If that's not possible, you can specify the core on which to run the Scylla Manager Agent.
+
+.. code-block:: none
+
+ cpu: 0
+
+Log level settings
+==================
+
+In this section, you can set the Log level settings which specify log output and level. Available log levels are ``error``, ``info`` and ``debug``.
+
+.. code-block:: none
+
+ logger:
+ level: info
+
+Scylla API settings
+===================
+
+In this section, you can set the Scylla API settings. Scylla Manager Agent pulls all needed configuration options from the ``scylla.yaml`` file. In order to do this, Scylla Manager Agent needs to know where the Scylla API is exposed. You should copy the ``api_address`` and ``api_port`` values from ``/etc/scylla/scylla.yaml`` and add them here:
+
+.. code-block:: none
+
+ #scylla:
+ # api_address: 0.0.0.0
+ # api_port: 10000
+
+Backup S3 settings
+==================
+
+In this section, you configure the AWS credentials (if required) for the backup location.
+
+IAM Role
+--------
+
+.. note:: If you are setting an IAM role in AWS, you do not need to change this section.
+
+.. _manager-2.1-aws-credentials:
+
+AWS credentials
+---------------
+
+.. note:: Completing this section in the scylla-manager-agent.yaml file is mandatory if you are not using an IAM role. Make sure you understand the security ramifications of placing AWS credentials into the yaml file.
+
+Fill in the information below with your AWS Credentials information.
+If you do not know where your keys are located, read the `AWS Security Blogs <https://aws.amazon.com/blogs/security/wheres-my-secret-access-key/>`_ or `documentation <https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys>`_ for information.
+
+.. code-block:: none
+
+ s3:
+ # S3 credentials, it's recommended to use IAM roles if possible, otherwise set
+ # your AWS Access Key ID and AWS Secret Access Key (password) here.
+ access_key_id: <your access key id>
+ secret_access_key: <your secret access key>
+
+MinIO and other AWS S3 alternatives
+-----------------------------------
+
+Backup can work with MinIO and other AWS S3 compatible providers.
+The available options are:
+
+* Alibaba,
+* Ceph,
+* DigitalOcean,
+* IBMCOS,
+* Minio,
+* Wasabi,
+* Dreamhost,
+* Netease.
+
+To configure S3 with a 3rd-party provider, in addition to credentials, one needs to specify ``provider`` parameter with one of the above options.
+If the service is self-hosted, it's also needed to specify ``endpoint`` with its base URL address.
+
+.. code-block:: none
+
+ s3:
+ # S3 credentials, it's recommended to use IAM roles if possible, otherwise set
+ # your AWS Access Key ID and AWS Secret Access Key (password) here.
+ access_key_id: <your access key id>
+ secret_access_key: <your secret access key>
+ # Provider of the S3 service. By default, this is AWS. There are multiple S3
+ # API compatible providers that can be used instead. Due to minor differences
+ # between them we require that exact provider is specified here for full
+ # compatibility. Supported and tested options are: AWS and Minio.
+ # The available providers are: Alibaba, AWS, Ceph, DigitalOcean, IBMCOS, Minio,
+ # Wasabi, Dreamhost, Netease.
+ provider: Minio
+ #
+ # Endpoint for S3 API, only relevant when using S3 compatible API.
+ endpoint: <your MinIO instance URL>
+
+Advanced settings
+-----------------
+
+.. code-block:: none
+
+ #s3:
+ # The server-side encryption algorithm used when storing this object in S3.
+ # If using KMS ID you must provide the ARN of Key.
+ # server_side_encryption:
+ # sse_kms_key_id:
+ #
+ # Number of files uploaded concurrently, by default it's 2.
+ # upload_concurrency: 2
+ #
+ # Maximum size (in bytes) of the body of a single request to S3 when uploading big files.
+ # Big files are cut into chunks. This value allows specifying how much data
+ # single request to S3 can carry. Bigger value allows reducing the number of requests
+ # needed to upload files, increasing it may help with 5xx responses returned by S3.
+ # Default value is 50M, and the string representation of the value can be provided, for
+ # e.g. 1M, 1G, off.
+ # chunk_size: 50M
+ #
+ # AWS S3 Transfer acceleration
+ # https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration-examples.html
+ # use_accelerate_endpoint: false
+
+Additional resources
+====================
+
+Scylla Manager `Configuration file <../configuration-file>`_
diff --git a/docs/operating-scylla/manager/2.1/architecture.jpg b/docs/operating-scylla/manager/2.1/architecture.jpg
--- a/docs/operating-scylla/manager/2.1/architecture.jpg
+++ b/docs/operating-scylla/manager/2.1/architecture.jpg
null
diff --git a/docs/operating-scylla/manager/2.1/architecture.png b/docs/operating-scylla/manager/2.1/architecture.png
--- a/docs/operating-scylla/manager/2.1/architecture.png
+++ b/docs/operating-scylla/manager/2.1/architecture.png
null
diff --git a/docs/operating-scylla/manager/2.1/architecture.rst b/docs/operating-scylla/manager/2.1/architecture.rst
--- a/docs/operating-scylla/manager/2.1/architecture.rst
+++ b/docs/operating-scylla/manager/2.1/architecture.rst
@@ -0,0 +1,57 @@
+============
+Architecture
+============
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager is a product for database operations automation.
+It can manage multiple Scylla clusters and run cluster-wide tasks in a controlled and predictable way.
+Scylla Manager discovers cluster topology and is aware of nodes belonging to different datacenters.
+
+Deployment
+==========
+
+Scylla Manager consists of three components:
+
+* Server - a daemon that exposes REST API
+* sctool - a command-line interface (CLI) for interacting with the Server over the REST API
+* Agent - a small executable, installed on each Scylla node. The Server communicates with the Agent over REST HTTPS. The Agent communicates with the local Scylla node over the REST HTTP.
+
+The Server persists its data to a Scylla cluster that can run locally or run on an external cluster
+(see `Use a remote database for Scylla Manager <../use-a-remote-db>`_ for details).
+
+Optionally (but recommended), you can add Scylla Monitoring Stack to enable reporting of Scylla Manager metrics and alerts.
+
+The diagram below presents a logical view of Scylla Manager with a remote backend datastore managing multiple Scylla Clusters situated in datacenters.
+
+
+Each node has two connections with the Scylla Manager Server:
+
+* REST API connection - used for Scylla Manager and Scylla Manager Agent activities
+* CQL connection - used for the Scylla `Health Check <../health-check>`_
+
+Scylla Manager uses the following ports:
+
+====== ============================================ ========
+Port Description Protocol
+====== ============================================ ========
+10001 Scylla Manager Agent REST API TCP
+------ -------------------------------------------- --------
+56080 Scylla Manager HTTP (default) HTTP
+------ -------------------------------------------- --------
+56443 Scylla Manager HTTPS (default) HTTPS
+------ -------------------------------------------- --------
+56090 Scylla Manager Prometheus API HTTP
+------ -------------------------------------------- --------
+56090 Scylla Manager Agent Prometheus API TCP
+====== ============================================ ========
+
+
+.. image:: architecture.png
+
+Additional Resources
+====================
+
+* `Install Scylla Manager <../install>`_
+* `Install Scylla Manager Agent <../install-agent>`_
+* `sctool Reference <../sctool>`_
diff --git a/docs/operating-scylla/manager/2.1/backup.rst b/docs/operating-scylla/manager/2.1/backup.rst
--- a/docs/operating-scylla/manager/2.1/backup.rst
+++ b/docs/operating-scylla/manager/2.1/backup.rst
@@ -0,0 +1,330 @@
+======
+Backup
+======
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Using sctool, you can backup and restore your managed Scylla clusters under Scylla Manager.
+Backups are scheduled in the same manner as repairs. You can start, stop, and track backup operations on demand.
+Scylla Manager can backup to Amazon S3 and S3 compatible API storage providers such as Ceph or MinIO.
+
+
+Benefits of using Scylla Manager backups
+========================================
+
+Scylla Manager automates the backup process and allows you to configure how and when a backup occurs.
+The advantages of using Scylla Manager for backup operations are:
+
+* Data selection - backup a single table or an entire cluster, the choice is up to you
+* Data deduplication - prevents multiple uploads of the same SSTable
+* Data retention - purge old data automatically when all goes right, or failover when something goes wrong
+* Data throttling - control how fast you upload or Pause/resume the backup
+* Lower disruption to the workflow of the Scylla Manager Agent due to cgroups and/or CPU pinning
+* No cross-region traffic - configurable upload destination per datacenter
+
+The backup process
+==================
+
+The backup procedure consists of multiple steps executed sequentially.
+It runs parallel on all nodes unless you limit it with the ``--snapshot-parallel`` or ``--upload-parallel`` :ref:`flag <sctool-backup-parameters>`.
+
+#. **Snapshot** - Take a :term:`snapshot <Snapshot>` of data on each node (according to backup configuration settings).
+#. **Schema** - (Optional) Upload the schema CQL to the backup storage destination, this requires that you added the cluster with ``--username`` and ``--password`` flags. See :doc:`Add Cluster <add-a-cluster>` for reference.
+#. **Upload** - Upload the snapshot to the backup storage destination.
+#. **Manifest** - Upload the manifest file containing metadata about the backup.
+#. **Purge** - If the retention threshold has been reached, remove the oldest backup from the storage location.
+
+Prepare nodes for backup
+========================
+
+#. Create a storage location for the backup.
+ Currently, Scylla Manager supports `Amazon S3 buckets <https://aws.amazon.com/s3/>`_ .
+ You can use an S3 bucket that you already created.
+ We recommend using an S3 bucket in the same region where your nodes are to minimize cross-region data transfer costs.
+ In multi-dc deployments, you should create a bucket per datacenter, each located in the datacenter's region.
+#. Choose how you want to configure access to the S3 Bucket.
+ You can use an IAM role (recommended), or you can add your AWS credentials to the agent configuration file.
+ The latter method is less secure as you will be propagating each node with this security information, and in cases where you need to change the key, you will have to replace it on each node.
+
+**To use an IAM Role**
+
+#. Create an `IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html>`_ for the S3 bucket which adheres to your company security policy.
+#. `Attach the IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html#attach-iam-role>`_ to **each EC2 instance (node)** in the cluster.
+
+Sample IAM policy for *scylla-manager-backup* bucket:
+
+.. code-block:: none
+
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:GetBucketLocation",
+ "s3:ListBucket",
+ "s3:ListBucketMultipartUploads"
+ ],
+ "Resource": [
+ "arn:aws:s3:::scylla-manager-backup"
+ ]
+ },
+ {
+ "Effect": "Allow",
+ "Action": [
+ "s3:PutObject",
+ "s3:GetObject",
+ "s3:DeleteObject",
+ "s3:AbortMultipartUpload",
+ "s3:ListMultipartUploadParts"
+ ],
+ "Resource": [
+ "arn:aws:s3:::scylla-manager-backup/*"
+ ]
+ }
+ ]
+ }
+
+**To add your AWS credentials the Scylla Manager Agent configuration file**
+
+Edit the ``/etc/scylla-manager-agent/scylla-manager-agent.yaml``
+
+#. Uncomment the ``s3:`` line, for parameters, note the two spaces in front, it's a yaml file.
+#. Uncomment and set ``access_key_id`` and ``secret_access_key``, refer to :ref:`AWS Credentials Configuration <manager-2.1-aws-credentials>` for details.
+#. If NOT running in AWS EC2 instance, uncomment and set ``region`` to a region where you created the S3 bucket.
+
+Troubleshooting
+---------------
+
+To troubleshoot Node to S3 connectivity issues, you can run:
+
+.. code-block:: none
+
+ scylla-manager-agent check-location --debug --location s3:<your S3 bucket name>
+
+Schedule a backup
+=================
+
+The most recommended way to run a backup is across an entire cluster.
+Backups can be scheduled to run on single or multiple datacenters, keyspaces, or tables.
+The backup procedure can be customized, allowing you to plan your backups according to your IT policy.
+All parameters can be found in the :ref:`sctool reference <sctool-backup>`.
+If you want to check if all of your nodes can connect to the backup storage location, see `Perform a Dry Run of a Backup`_.
+
+**Prerequisites**
+
+#. Backup locations (S3 buckets) created.
+#. Access rights to backup locations granted to Nodes, see `Prepare Nodes for Backup`_.
+
+Create a scheduled backup
+-------------------------
+
+Use the example below to run the sctool backup command.
+
+.. code-block:: none
+
+ sctool backup -c <id|name> -L <list of locations> [-s <date>] [-i <time-unit>]
+
+where:
+
+* ``-c`` - the :ref:`name <sctool-cluster-add>` you used when you created the cluster
+* ``-L`` - points to backup storage location in ``s3:<your S3 bucket name>`` format or ``<your DC name>:s3:<your S3 bucket name>`` if you want to specify a location for a datacenter
+* ``-s`` - the time you want the backup to begin
+* ``-i`` - the time interval you want to use in between consecutive backups
+
+If you want to run the backup only once, see `Create an ad-hoc backup`_.
+In case when you want the backup to start immediately, but you want it to schedule it to repeat at a determined interval, leave out the start flag (``-s``) and set the interval flag (``-i``) to the time you want the backup to reoccur.
+
+Schedule a daily backup
+.......................
+
+This command will schedule a backup on 9th Dec 2019 at 15:15:06 UTC time zone, a backup will be repeated every day, and all the data will be stored in S3 under the ``my-backups`` bucket.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups' -s '2019-12-09T15:16:05Z' -i 24h
+ backup/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+Command returns the task ID (backup/3208ff15-6e8f-48b2-875c-d3c73f545410, in this case).
+This ID can be used to query the status of the backup task, to defer the task to another time, or to cancel the task See :ref:`Managing Tasks <sctool-managing-tasks>`.
+
+Schedule a daily, weekly, and monthly backup
+............................................
+This command series will schedule a backup on 9th Dec 2019 at 15:15:06 UTC time zone and will repeat the backup every day (keeping the last 7 days), every week (keeping the previous week), and every month (keeping the previous month).
+All the data will be stored in S3 under the ``my-backups`` bucket.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 7 -s '2019-12-09T15:16:05Z' -i 24h
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 2 -s '2019-12-09T15:16:05Z' -i 7d
+
+ sctool backup -c prod-cluster -L 's3:my-backups' --retention 1 -s '2019-12-09T15:16:05Z' -i 30d
+
+Schedule a backup for a specific DC, keyspace, or table
+--------------------------------------------------------
+In order to schedule a backup of a particular datacenter, you have to specify ``-dc`` parameter.
+You can specify more than one DC, or use a glob pattern to match multiple DCs or exclude some of them.
+
+For example, you have the following DCs in your cluster: dc1, dc2, dc3
+
+Backup one specific DC
+......................
+
+In this example you backup the only dc1 every 2 days.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster --dc 'dc1' -L 's3:dc1-backups' -i 2d
+
+
+Backup all DCs except for those specified
+.........................................
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d --dc '*,!dc2' -L 's3:my-backups'
+
+Backup to a specific location per DC
+....................................
+
+If your data centers are located in different regions, you can also specify different locations.
+If your buckets are created in the same regions as your data centers, you may save some bandwidth costs.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d --dc 'eu-dc,us-dc' -L 's3:eu-dc:eu-backups,s3:us-dc:us-backups'
+
+Backup a specific keyspace or table
+...................................
+
+In order to schedule a backup of a particular keyspace or table, you have to provide ``-K`` parameter.
+You can specify more than one keyspace/table or use a glob pattern to match multiple keyspaces/tables or exclude them.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -i 30d -K 'auth_service.*,!auth_service.lru_cache' --dc 'dc1' -L 's3:dc1-backups'
+
+Create an ad-hoc backup
+-----------------------
+
+An ad-hoc backup runs immediately and does not repeat.
+This procedure shows the most frequently used backup commands.
+Additional parameters can be used. Refer to :ref:`backup parameters <sctool-backup-parameters>`.
+
+**Procedure**
+
+To run an immediate backup on the prod-cluster cluster, saving the backup in my-backups, run the following command
+replacing the ``-c`` cluster flag with your cluster's cluster name or ID and replace the ``-L`` flag with your backup's location:
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:my-backups'
+
+Perform a dry run of a backup
+-----------------------------
+
+We recommend to use ``--dry-run`` parameter prior to scheduling a backup.
+It's a useful way to verify whether all necessary prerequisites are fulfilled.
+Add the parameter to the end of your backup command, so if it works, you can erase it and schedule the backup with no need to make any other changes.
+
+Dry run verifies if nodes are able to access the backup location provided.
+If it's not accessible, an error message will be displayed, and the backup is not be scheduled.
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:test-bucket' --dry-run
+ NOTICE: dry run mode, backup is not scheduled
+
+ Error: failed to get backup target: location is not accessible
+ 192.168.100.23: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+ 192.168.100.22: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+ 192.168.100.21: failed to access s3:test-bucket make sure that the location is correct and credentials are set
+
+The dry run gives you the chance to resolve all configuration or access issues before executing an actual backup.
+
+If the dry run completes successfully, a summary of the backup is displayed. For example:
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -L 's3:backups' --dry-run
+ NOTICE: dry run mode, backup is not scheduled
+
+ Data Centers:
+ - dc1
+ - dc2
+ Keyspaces:
+ - system_auth all (2 tables)
+ - system_distributed all (1 table)
+ - system_traces all (5 tables)
+ - auth_service all (3 tables)
+
+ Disk size: ~10.4GB
+
+ Locations:
+ - s3:backups
+ Bandwidth Limits:
+ - Unlimited
+ Snapshot Parallel Limits:
+ - All hosts in parallel
+ Upload Parallel Limits:
+ - All hosts in parallel
+
+ Retention: Last 3 backups
+
+List the contents of a specific backup
+=======================================
+
+List all backups in s3
+----------------------
+
+Lists all backups currently in storage that are managed by Scylla Manager.
+
+.. code-block:: none
+
+ sctool backup list -c prod-cluster
+ Snapshots:
+ - sm_20191210145143UTC
+ - sm_20191210145027UTC
+ - sm_20191210144833UTC
+ Keyspaces:
+ - system_auth (2 tables)
+ - system_distributed (1 table)
+ - system_traces (5 tables)
+ - auth_service (3 tables)
+
+List files that were uploaded during a specific backup
+-------------------------------------------------------
+
+You can list all files that were uploaded during a particular backup.
+
+To list the files use:
+
+.. code-block:: none
+
+ sctool backup files -c prod-cluster --snapshot-tag sm_20191210145027UTC
+
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-CompressionInfo.db auth_service/roles
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-Data.db auth_service/roles
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-Digest.crc32 auth_service/roles
+ [...]
+
+Additional resources
+--------------------
+
+:doc:`Scylla Snapshots </kb/snapshots>`
+
+Delete backup snapshot
+=========================
+
+If you decide that you don't want to wait until a particular snapshot expires according to its retention policy, there is a command which allows you to delete a single snapshot from a provided location.
+
+This operation is aware of the Manager deduplication policy and will not delete any SSTable file referenced by another snapshot.
+
+.. warning:: This operation is irreversible! Use it with great caution!
+
+.. code-block:: none
+
+ sctool backup delete -c prod-cluster -L s3:backups --snapshot-tag sm_20191210145027UTC
+
+Once a snapshot is deleted, it won't show up in the backup listing anymore.
diff --git a/docs/operating-scylla/manager/2.1/configuration-file.rst b/docs/operating-scylla/manager/2.1/configuration-file.rst
--- a/docs/operating-scylla/manager/2.1/configuration-file.rst
+++ b/docs/operating-scylla/manager/2.1/configuration-file.rst
@@ -0,0 +1,179 @@
+==================
+Configuration file
+==================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+Scylla Manager has a single configuration file ``/etc/scylla-manager/scylla-manager.yaml``.
+Note that the file will open as read-only unless you edit it as the root user or by using sudo.
+Usually, there is no need to edit the configuration file.
+
+HTTP/HTTPS server settings
+==========================
+
+With server settings, you may specify if Scylla Manager should be available over HTTP, HTTPS, or both.
+
+.. code-block:: yaml
+
+ # Bind REST API to the specified TCP address using HTTP protocol.
+ # http: 127.0.0.1:56080
+
+ # Bind REST API to the specified TCP address using HTTPS protocol.
+ https: 127.0.0.1:56443
+
+Prometheus settings
+===================
+
+.. code-block:: yaml
+
+ # Bind prometheus API to the specified TCP address using HTTP protocol.
+ # By default it binds to all network interfaces, but you can restrict it
+ # by specifying it like this 127:0.0.1:56090 or any other combination
+ # of ip and port.
+ prometheus: ':56090'
+
+If changing prometheus IP or port, please remember to adjust rules in :doc:`prometheus server </operating-scylla/monitoring/2.2/monitoring-stack>`.
+
+.. code-block:: yaml
+
+ - targets:
+ - IP:56090
+
+Debug endpoint settings
+=======================
+
+In this section, you can specify the pprof debug server address.
+It allows you to run profiling on demand on a live application.
+By default, the server is running on port ``56112``.
+
+.. code-block:: none
+
+ debug: 127.0.0.1:56112
+
+.. _manager-2.1-logging-settings:
+
+Logging settings
+================
+
+Logging settings specify log output and level.
+
+.. code-block:: yaml
+
+ # Logging configuration.
+ logger:
+ # Where to output logs, syslog or stderr.
+ mode: syslog
+ # Available log levels are error, info, and debug.
+ level: info
+
+Database settings
+=================
+
+Database settings allow for `using a remote cluster <../use-a-remote-db>`_ to store Scylla Manager data.
+
+.. code-block:: yaml
+
+ # Scylla Manager database, used to store management data.
+ database:
+ hosts:
+ - 127.0.0.1
+ # Enable or disable client/server encryption.
+ # ssl: false
+ #
+ # Database credentials.
+ # user: user
+ # password: password
+ #
+ # Local datacenter name, specify if using a remote, multi-dc cluster.
+ # local_dc:
+ #
+ # Database connection timeout.
+ # timeout: 600ms
+ #
+ # Keyspace for management data, for create statement see /etc/scylla-manager/create_keyspace.cql.tpl.
+ # keyspace: scylla_manager
+ # replication_factor: 1
+
+ # Optional custom client/server encryption options.
+ #ssl:
+ # CA certificate used to validate server cert. If not set, will use he host's root CA set.
+ # cert_file:
+ #
+ # Verify the hostname and server cert.
+ # validate: true
+ #
+ # Client certificate and key in PEM format. It has to be provided when
+ # client_encryption_options.require_client_auth=true is set on server.
+ # user_cert_file:
+ # user_key_file
+
+Health check settings
+=====================
+
+Health check settings let you specify the timeout threshold.
+If there is no response from a node after this time period is reached, the :ref:`status <sctool_status>` report (``sctool status``) shows the node as ``DOWN``.
+
+.. code-block:: yaml
+
+ # Healthcheck service configuration.
+ #healthcheck:
+ # Timeout for CQL status checks.
+ # timeout: 250ms
+ # ssl_timeout: 750ms
+
+Backup settings
+===============
+
+Backup settings let you specify backup parameters.
+
+.. code-block:: yaml
+
+ # Backup service configuration.
+ #backup:
+ # Minimal amount of free disk space required to take a snapshot.
+ # disk_space_free_min_percent: 10
+ #
+ # Maximal time for a backup run to be considered fresh and can be continued from
+ # the same snapshot. If exceeded, a new run with a new snapshot will be created.
+ # Zero means no limit.
+ # age_max: 12h
+
+Repair settings
+===============
+
+Repair settings let you specify repair parameters.
+
+.. code-block:: yaml
+
+ # Repair service configuration.
+ #repair:
+ # Number of segments repaired by Scylla in a single repair command. Increase
+ # this value to make repairs faster, note that this may result in increased load
+ # on the cluster.
+ # segments_per_repair: 1
+ #
+ # Maximal number of shards on a host repaired at the same time. By default all
+ # shards are repaired in parallel.
+ # shard_parallel_max: 0
+ #
+ # Maximal allowed number of failed segments per shard. In case of a failure
+ # to repair a segment Scylla Manager will try to repair it multiple times
+ # depending on the specified number of retries (default 3). If the
+ # shard_failed_segments_max limit is exceeded repair task will immediately
+ # fail, and the next repair run will start the repair procedure from the beginning.
+ # shard_failed_segments_max: 25
+ #
+ # In case of an error, hold back repair for the specified amount of time.
+ # error_backoff: 5m
+ #
+ # Frequency Scylla Manager poll Scylla node for repair command status.
+ # poll_interval: 200ms
+ #
+ # Maximal time a paused repair is considered fresh and can be continued,
+ # if an exceeded repair will start from the beginning. Zero means no limit.
+ # age_max: 0
+ #
+ # Distribution of data among cores (shards) within a node.
+ # Copy value from Scylla configuration file.
+ # murmur3_partitioner_ignore_msb_bits: 12
diff --git a/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst b/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
--- a/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
+++ b/docs/operating-scylla/manager/2.1/extract-schema-from-backup.rst
@@ -0,0 +1,40 @@
+==============================
+Extract schema from the backup
+==============================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. versionadded:: 2.1 Scylla Manager
+
+The first step to restoring a Scylla Manager backup is to restore the CQL schema from a text file.
+Scylla Manager version 2.1 creates a backup up of matching schema along with the snapshot.
+If you created the backup with Scylla Manager version 2.0 or you didn't provide credentials for a schema backup in Scylla Manager version 2.1, follow the instructions in `how to restore your schema from system table <../../2.0/extract-schema-from-system-table/>`_.
+
+If not, follow these steps to restore the schema from the Scylla Manager backup that has the schema stored along with the snapshot:
+
+**Procedure**
+
+#. List available backups:
+
+ .. code-block:: none
+
+ sctool backup list --cluster my-cluster --location s3:backup-bucket
+
+#. List files located in snapshot you want to restore. The first line contains a path to the schema so pipe it to ``aws s3 cp`` for download it to the current directory. For example:
+
+ .. code-block:: none
+
+ sctool backup files --cluster my-cluster -L s3:backup-bucket -T sm_20200513104924UTC --with-version | head -n 1 | xargs -n2 aws s3 cp
+ download: s3://backup-bucket/backup/schema/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz to ./task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz
+
+
+#. Create a directory to store the schema files and extract the archive containing the schema.
+
+ .. code-block:: none
+
+ mkdir ./schema
+ tar -xf task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz -C ./schema
+ ls ./schema
+ system_auth.cql system_distributed.cql system_schema.cql system_traces.cql user_data.cql
+
+Listed files are schema files for each keyspace in the backup. You can use each cql file to restore needed keyspace and continue the :ref:`restore procedure <restore-backup-restore-schema>`
diff --git a/docs/operating-scylla/manager/2.1/health-check.rst b/docs/operating-scylla/manager/2.1/health-check.rst
--- a/docs/operating-scylla/manager/2.1/health-check.rst
+++ b/docs/operating-scylla/manager/2.1/health-check.rst
@@ -0,0 +1,85 @@
+====================
+Cluster Health Check
+====================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager automatically adds a health check task to all new nodes when the cluster is added to the Scylla Manager and to all existing nodes
+during the upgrade procedure. You can see the tasks created by the healthcheck when you run
+the :ref:`sctool task list <sctool-task-list>` command.
+
+For example:
+
+.. code-block:: none
+
+ sctool task list -c manager-testcluster
+
+returns:
+
+.. code-block:: none
+
+ Cluster: manager-testcluster
+ ╭──────────────────────────────────────────────────────┬───────────────────────────────┬──────┬───────────┬────────╮
+ │ task │ next run │ ret. │ arguments │ status │
+ ├──────────────────────────────────────────────────────┼───────────────────────────────┼──────┼───────────┼────────┤
+ │ healthcheck/018da854-b9ff-4e0a-bae7-ca65c677c559 │ 02 Apr 19 18:06:31 UTC (+15s) │ 0 │ │ NEW │
+ │ healthcheck_api/597f237f-103d-4994-8167-3ff591150b7e │ 02 Apr 19 18:07:01 UTC (+1h) │ 0 │ │ NEW │
+ │ repair/21006f88-0c8c-4e11-9e84-83c319f80d0c │ 03 Apr 19 00:00:00 UTC (+7d) │ 3/3 │ │ NEW │
+ ╰──────────────────────────────────────────────────────┴───────────────────────────────┴──────┴───────────┴────────╯
+
+The health check task ensures that CQL native port is accessible on all the nodes. For each node, in parallel,
+Scylla Manager opens a connection to a CQL port and asks for server options. If there is no response or the response takes longer than 250 milliseconds, the node is considered to be DOWN otherwise, the node is considered to be UP.
+The results are available using the :ref:`sctool status <sctool_status>` command.
+
+For example:
+
+.. code-block:: none
+
+ sctool status -c prod-cluster2
+
+returns:
+
+.. code-block:: none
+
+ Datacenter: dc1
+ ╭──────────┬─────┬──────────┬────────────────╮
+ │ CQL │ SSL │ REST │ Host │
+ ├──────────┼─────┼──────────┼────────────────┤
+ │ UP (2ms) │ OFF │ UP (1ms) │ 192.168.100.11 │
+ │ UP (1ms) │ OFF │ UP (0ms) │ 192.168.100.12 │
+ │ UP (2ms) │ OFF │ UP (0ms) │ 192.168.100.13 │
+ ╰──────────┴─────┴──────────┴────────────────╯
+ Datacenter: dc2
+ ╭──────────┬─────┬──────────┬────────────────╮
+ │ CQL │ SSL │ REST │ Host │
+ ├──────────┼─────┼──────────┼────────────────┤
+ │ UP (2ms) │ OFF │ UP (1ms) │ 192.168.100.21 │
+ │ UP (1ms) │ OFF │ UP (1ms) │ 192.168.100.22 │
+ │ UP (1ms) │ OFF │ UP (1ms) │ 192.168.100.23 │
+ ╰──────────┴─────┴──────────┴────────────────╯
+
+If you have enabled the Scylla Monitoring stack, the Scylla Manager dashboard includes the same cluster status report.
+In addition, the Prometheus Alert Manager has an alert to report when a Scylla node health check fails.
+
+Scylla Manager just works!
+It reads CQL IP address and port from node configuration and can automatically detect TLS/SSL connection.
+There are two types of CQL health check `Credentials agnostic health check`_ and `CQL query health check`_.
+
+.. _manager-2.1-credentials-agnostic-health-check:
+
+Credentials agnostic health check
+---------------------------------
+
+Scylla Manager does not require database credentials to work.
+CQL health check is based on sending `CQL OPTIONS frame <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec#L302>`_ and does not start a CQL session.
+This is simple and effective but does not test CQL all the way down.
+For that, you may consider upgrading to `CQL query health check`_.
+
+.. _manager-2.1-cql-query-health-check:
+
+CQL query health check
+----------------------
+
+You may specify CQL ``username`` and ``password`` flags when adding a cluster to Scylla Manager using :ref:`sctool cluster add command <sctool-cluster-add>`.
+It's also possible to add or change that using :ref:`sctool cluster update command <sctool-cluster-update>`.
+Once Scylla Manager has CQL credential to the cluster, when performing a health check, it would try to connect to each node and execute ``SELECT now() FROM system.local`` query.
diff --git a/docs/operating-scylla/manager/2.1/index.rst b/docs/operating-scylla/manager/2.1/index.rst
--- a/docs/operating-scylla/manager/2.1/index.rst
+++ b/docs/operating-scylla/manager/2.1/index.rst
@@ -0,0 +1,46 @@
+:orphan:
+Scylla Manager 2.1
+==================
+.. toctree::
+ :hidden:
+
+ architecture
+ Install Scylla Manager <install>
+ Install Scylla Manager Agent <install-agent>
+ add-a-cluster
+ repair
+ backup
+ extract-schema-from-backup
+ restore-a-backup
+ health-check
+ sctool
+ monitoring-manager-integration
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+ use-a-remote-db
+ configuration-file
+ agent-configuration-file
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. panel-box::
+ :title: Scylla Manager
+ :id: "getting-started"
+ :class: my-panel
+
+ .. include:: /operating-scylla/manager/2.1/_common/manager-description.rst
+
+ * :doc:`Architecture <architecture>`
+ * :doc:`Install Scylla Manager <install>`
+ * :doc:`Install Scylla Manager Agent <install-agent>`
+ * :doc:`Add a cluster or a node to Scylla Manager <add-a-cluster>`
+ * :doc:`Repair <repair>`
+ * :doc:`Backup <backup>`
+ * :doc:`Extract schema from the backup <extract-schema-from-backup>`
+ * :doc:`Restore a backup <restore-a-backup>`
+ * :doc:`Health Check <health-check>`
+ * :doc:`sctool CLI Reference <sctool>`
+ * :doc:`Integration with Scylla Monitoring Stack <monitoring-manager-integration>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Use a remote database for Scylla Manager <use-a-remote-db>`
+ * :doc:`Configuration file <configuration-file>`
+ * :doc:`Scylla Manager Agent Configuration file <agent-configuration-file>`
diff --git a/docs/operating-scylla/manager/2.1/install-agent.rst b/docs/operating-scylla/manager/2.1/install-agent.rst
--- a/docs/operating-scylla/manager/2.1/install-agent.rst
+++ b/docs/operating-scylla/manager/2.1/install-agent.rst
@@ -0,0 +1,181 @@
+=================================
+Scylla Manager Agent Installation
+=================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+Scylla Manager Agent is an executable, installed on each Scylla node.
+The Server communicates with the Agent over REST/HTTPS.
+The Agent communicates with the local Scylla node over the REST/HTTP.
+
+
+
+Install Scylla Manager Agent
+----------------------------
+
+Prerequisites
+=============
+
+* Scylla cluster running on any :doc:`OS supported by Scylla Manager 2.0 </getting-started/os-support>`
+* Traffic on port 10001 unblocked to Scylla nodes from the dedicated host
+
+.. note:: Scylla Manager only works with Scylla clusters that are using the Murmur3 partitioner (Scylla default partitioner). To check your cluster's partitioner, run the cqlsh command ``DESCRIBE CLUSTER``.
+
+Download packages
+=================
+
+**Procedure**
+
+Download and install Scylla Manager Agent (from the Scylla Manager Download Page) according to the desired version:
+
+* `Scylla Manager for Open Source <https://www.scylladb.com/download/open-source/scylla-manager/>`_ - Registration Required
+* Scylla Enterprise - Login to the `Customer Portal <https://www.scylladb.com/customer-portal/>`_
+
+Configure Scylla Manager Agent
+------------------------------
+There are three steps you need to complete:
+
+#. `Generate an authentication token`_
+#. Place the token parameters from `Configure authentication token parameters`_ in the Agent configuration file
+#. `Start Scylla Manager Agent service`_ or restart if already running. Confirm the service starts / restarts and runs without errors
+
+
+.. _manager-2.1-generate-auth-token:
+
+Generate an authentication token
+================================
+
+**Procedure**
+
+#. Generate an authentication token to be used to authenticate Scylla Manager with Scylla nodes.
+ This procedure is done **once** for each cluster. It is recommended to use a different token for each cluster.
+
+ .. note:: Use the same token on all nodes in the same cluster.
+
+ From **one node only** Run the token generator script.
+
+ For example:
+
+ .. code-block:: none
+
+ $ scyllamgr_auth_token_gen
+ 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+ If you want to change the token, you will need to repeat this procedure and place the new token on all nodes.
+ This procedure sets up the Scylla agent on each node.
+ Repeat the procedure for **every** Scylla node in the cluster that you want to be managed under Scylla Manager.
+
+
+Run `scyllamgr_agent_setup` script
+==================================
+
+**Procedure**
+
+#. Run the setup script to setup environment for the agent:
+
+ .. note:: Script requires sudo rights
+
+ .. code-block:: none
+
+ $ sudo scyllamgr_agent_setup
+ Do you want to create scylla-helper.slice if it does not exist?
+ Yes - limit Scylla Manager Agent and other helper programs memory. No - skip this step.
+ [YES/no] YES
+ Do you want the Scylla Manager Agent service to automatically start when the node boots?
+ Yes - automatically start Scylla Manager Agent when the node boots. No - skip this step.
+ [YES/no] YES
+
+ The first step relates to limited resources that are available to the agent, and second instructs systemd to run agent on node restart.
+
+.. _manager-2.1-configure-auth-token:
+
+Configure authentication token parameters
+=========================================
+
+**Procedure**
+
+#. Take the authentication token you generated from `Generate an authentication token`_, and place it into ``/etc/scylla-manager-agent/scylla-manager-agent.yaml`` as part of the ``auth_token`` :ref:`section <manger-2.1-agent-configuration-file-auth-token>`.
+
+ For Example:
+
+ .. code-block:: none
+
+ $ cat /etc/scylla-manager-agent/scylla-manager-agent.yaml
+ # Scylla Manager Agent config YAML
+
+ # Specify authentication token, the auth_token needs to be the same for all the
+ # nodes in a cluster. Use scyllamgr_auth_token_gen to generate the auth_token
+ # value.
+ auth_token: 6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM
+
+
+Start Scylla Manager Agent service
+==================================
+
+**Procedure**
+
+#. Start Scylla Manager Agent service
+
+ .. code-block:: none
+
+ $ sudo systemctl start scylla-manager-agent
+
+#. Validate Scylla Manager Agent is running
+
+ .. code-block:: none
+
+ $ sudo systemctl status scylla-manager-agent
+ ● scylla-manager-agent.service - Scylla Manager Agent
+ Loaded: loaded (/usr/lib/systemd/system/scylla-manager-agent.service; disabled; vendor preset: disabled)
+ Active: active (running) since Wed 2019-10-30 10:46:51 UTC; 7s ago
+ Main PID: 14670 (scylla-manager-)
+ CGroup: /system.slice/scylla-manager-agent.service
+ └─14670 /usr/bin/scylla-manager-agent
+
+#. Enable the Scylla Manager Agent to run when the node starts.
+
+ .. code-block:: none
+
+ $ sudo systemctl enable scylla-manager-agent
+
+
+#. Repeat the procedure for **every** Scylla node in the cluster that you want to be managed under Scylla Manager, starting with `Configure authentication token parameters`_.
+
+.. _manager-2.1-prepare-nodes-for-backup:
+
+Prepare nodes for backup
+------------------------
+
+Adding the cluster to Scylla Manager automatically creates a backup task. Validate the connection to your backup location is accessible from Scylla Manager before adding the cluster to avoid errors.
+
+**Procedure**
+
+#. Create a storage location for the backup.
+ Currently, Scylla Manager 2.1 supports `S3 buckets <https://aws.amazon.com/s3/>`_ created on AWS.
+ You can use an S3 bucket that you already created.
+#. Choose how you want to configure access to the S3 Bucket.
+ You can use an IAM role (recommended), or you can add your AWS credentials to the agent configuration file.
+ This method is less secure as you will be propagating each node with this security information, and in cases where you need to change the key, you will have to replace it on each node.
+
+ * To use an IAM Role:
+
+ #. Create an `IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html>`_ for the S3 bucket which adheres to your company security policy. You can use the role you already created.
+ #. `Attach the IAM role <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide//iam-roles-for-amazon-ec2.html#attach-iam-role>`_ to **each EC2 instance (node)** in the cluster.
+
+ * To add your AWS credentials the Scylla Manager Agent configuration file:
+
+ #. Edit the ``/etc/scylla-manager-agent/scylla-manager-agent.yaml`` in the ``S3`` section your authentication information about the S3 bucket.
+ Refer to :ref:`AWS Credentials Configuration <manager-2.1-aws-credentials>` for details.
+
+#. Validate that the manager has access to the backup location.
+ If there is no response, the S3 bucket is accessible. If not, you will see an error.
+
+ .. code-block:: none
+
+ $ scylla-manager-agent check-location --location s3:<your S3 bucket name>
+
+
+Register a cluster
+------------------
+
+Continue with `Add a Cluster <../add-a-cluster>`_.
diff --git a/docs/operating-scylla/manager/2.1/install.rst b/docs/operating-scylla/manager/2.1/install.rst
--- a/docs/operating-scylla/manager/2.1/install.rst
+++ b/docs/operating-scylla/manager/2.1/install.rst
@@ -0,0 +1,132 @@
+===========================
+Scylla Manager Installation
+===========================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+System requirements
+===================
+
+Scylla Manager Server has modest systems requirements.
+While a minimal server can run on a system with 2 cores and 1GB RAM, the following configuration is recommended:
+
+* **CPU** - 2vCPUs
+* **Memory** - 8GB+ DRAM
+
+.. note:: If you are running :doc:`Scylla Monitoring Stack </operating-scylla/monitoring/2.2/monitoring-stack>` on the same server as Scylla Manager, your system should also meet the minimal :doc:`Monitoring requirements </operating-scylla/monitoring/2.2/monitoring-stack>`.
+
+Installation workflow
+=====================
+
+#. `Install Scylla Manager`_
+#. `Run the scyllamgr_setup script`_
+#. `Enable Bash Script Completion`_
+#. `Start Scylla Manager Service`_ and verify Scylla Manager is Running and that sctool is running
+
+
+Install Scylla Manager
+----------------------
+
+Choose one of the following installation methods:
+
+**Scylla Manager for Scylla Enterprise**
+
+#. Download and install Scylla Manager from the `Enterprise Download page <https://www.scylladb.com/download/enterprise/#manager>`_.
+#. Follow the entire installation procedure.
+#. Continue with `Run the scyllamgr_setup script`_.
+
+**Scylla Manager for Scylla Open Source**
+
+#. On the same node as you are installing Scylla Manager, download and install Scylla as a local database from the `Scylla Open Source Download page <https://www.scylladb.com/download/open-source/>`_.
+ There is no need to run the Scylla setup as it is taken care of by the ``scyllamgr_setup`` script.
+#. Download and Install Scylla Manager from the `Scylla Manager Open Source Download page <https://www.scylladb.com/download/open-source/scylla-manager/>`_.
+#. Follow the entire installation procedure.
+#. Continue with `Run the scyllamgr_setup script`_.
+
+.. _install-run-the-scylla-manager-setup-script:
+
+Run the scyllamgr_setup script
+------------------------------
+
+The Scylla Manager setup script automates the configuration of Scylla Manager by asking you some simple questions.
+It can be run in non-interactive mode if you'd like to script it.
+
+There are three decisions you need to make:
+
+* Do you want to enable the service to start automatically? If not, you will have to start the service manually each time you want to use it.
+* Do you want to set up and enable a local Scylla backend? If not, you will need to set up a `remote DB <../use-a-remote-db>`_
+* Do you want Scylla Manager to check periodically if updates are available? If not, you will need to check yourself.
+
+.. code-block:: none
+
+ scyllamgr_setup -h
+ Usage: scyllamgr_setup [-y][--no-scylla-setup][--no-enable-service][--no-check-for-updates]
+
+ Options:
+ -y, --assume-yes assume that the answer to any question which would be asked is yes
+ --no-scylla-setup skip setting up and enabling local Scylla instance as a storage backend for Scylla Manager
+ --no-enable-service skip enabling service
+ --no-check-for-updates skip enabling periodic check for updates
+ -h, --help print this help
+
+ Interactive mode is enabled when no flags are provided.
+
+**Procedure**
+
+#. Run the ``scyllamgr_setup`` script to configure the service. You can run the script in interactive mode (no flags) or automate your decision making by using flags.
+
+Enable bash script completion
+-----------------------------
+
+Enable bash completion for sctool: the Scylla Manager CLI. Alternatively, you can just open a new terminal.
+
+.. code-block:: none
+
+ source /etc/bash_completion.d/sctool.bash
+
+Start Scylla Manager service
+============================
+
+Scylla Manager integrates with ``systemd`` and can be started and stopped using ``systemctl`` command.
+
+**Procedure**
+
+#. Start the Scylla Manager server service.
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-manager.service
+
+#. Verify the Scylla Manager server service is running.
+
+ .. code-block:: none
+
+ sudo systemctl status scylla-manager.service
+ ● scylla-manager.service - Scylla Manager Server
+ Loaded: loaded (/usr/lib/systemd/system/scylla-manager.service; enabled; vendor preset: disabled)
+ Active: active (running) since Wed 2019-10-30 11:00:01 UTC; 20s ago
+ Main PID: 5805 (scylla-manager)
+ CGroup: /system.slice/scylla-manager.service
+ └─5805 /usr/bin/scylla-manager
+
+ ...
+
+ Hint: Some lines were ellipsized, use -l to show in full.
+
+
+#. Confirm sctool is running by displaying the sctool version.
+
+ .. code-block:: none
+
+ sctool version
+ Client version: 2.1-0.20200401.ce91f2ad
+ Server version: 2.1-0.20200401.ce91f2ad
+
+
+.. note:: The first time you run this command, Scylla Manager may take a few seconds to start because it must create the database schema.
+
+Install Scylla Manager Agent
+============================
+
+Continue with `Setup Scylla Manager Agent <../install-agent>`_
diff --git a/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst b/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
--- a/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
+++ b/docs/operating-scylla/manager/2.1/monitoring-manager-integration.rst
@@ -0,0 +1,11 @@
+========================================
+Integration with Scylla Monitoring Stack
+========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+When used with Scylla Manager, the metrics for all of your managed clusters and alerts can be viewed using Scylla Monitoring.
+The Monitoring stack 2.1 Manager dashboard displays progress for all tasks, including: repairs, backups, node status, Scylla Manager status, and other metrics and Alerts.
+For more information, refer to the :doc:`Scylla Monitoring </operating-scylla/monitoring/index>` documentation.
+
+.. todo-add screenshot
diff --git a/docs/operating-scylla/manager/2.1/repair.rst b/docs/operating-scylla/manager/2.1/repair.rst
--- a/docs/operating-scylla/manager/2.1/repair.rst
+++ b/docs/operating-scylla/manager/2.1/repair.rst
@@ -0,0 +1,186 @@
+======
+Repair
+======
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+.. note:: If, after upgrading to the latest Scylla, you experience repairs that are slower than usual please consider :doc:`upgrading Scylla Manager to the appropriate version </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+When you create a cluster, a repair job is automatically scheduled.
+This task is set to occur each week by default, but you can change it to another time or add additional repair tasks.
+It is important to make sure that data across the nodes is consistent when maintaining your clusters.
+
+
+Why repair with Scylla Manager
+-------------------------------
+
+Scylla Manager automates the repair process and allows you to manage how and when the repair occurs.
+The advantage of repairing the cluster with Scylla Manager is:
+
+* Clusters are repaired node by node, ensuring that each database shard performs exactly one repair task at a time.
+ This gives the best repair parallelism on a node, shortens the overall repair time, and does not introduce unnecessary load.
+
+* If there is an error, Scylla Manager’s retry mechanism will try to run the repair again up to the number of retries that you set.
+
+* It has a restart (pause) mechanism that allows for restarting a repair from where it left off.
+
+* Repair what you want, when you want, and how often you want. Manager gives you that flexibility.
+
+* The most apparent advantage is that with Manager you do not have to manually SSH into every node as you do with nodetool.
+
+What can you repair with Scylla Manager
+----------------------------------------
+
+Scylla Manager can repair any item which it manages, specifically:
+
+* Specific tables, keyspaces, clusters, or data centers.
+
+* A group of tables, keyspaces, clusters or data centers.
+
+* All tables, keyspaces, clusters, or data centers.
+
+
+What sort of repairs can I run with Scylla Manager
+---------------------------------------------------
+
+You can run two types of repairs:
+
+* Ad-hoc - this is a one time repair
+
+* Scheduled - this repair is scheduled in advance and can repeat
+
+.. _manager-2.1-schedule-a-repair:
+
+Schedule a Repair
+-----------------
+
+By default, a cluster successfully added to Scylla Manager has a repair task created for it, which repairs the entire cluster.
+This is a repeating task that runs every week.
+You can change this repair, add additional repairs, or delete this repair.
+You can schedule repairs to run in the future on a regular basis, schedule repairs to run once, or schedule repairs to run immediately on an as-needed basis.
+Any repair can be rescheduled, paused, resumed, or deleted.
+For information on what is repaired and the types of repairs available, see `What can you repair with Scylla Manager`_.
+
+Create a scheduled repair
+.........................
+
+While the most recommended way to run a repair is across an entire cluster, repairs can be scheduled to run on a single/multiple datacenters, keyspaces, or tables.
+Scheduled repairs run every X days, depending on the frequency you set.
+The procedure here shows the most frequently used repair command.
+Additional parameters are located in the :ref:`sctool Reference <sctool-repair-parameters>`.
+
+**Procedure**
+
+Run the following sctoool repair command, replacing the parameters with your own parameters:
+
+* ``-c`` - cluster name - replace `prod-cluster` with the name of your cluster
+
+* ``-s`` - start-time - replace 2018-01-02T15:04:05-07:00 with the time you want the repair to begin
+
+* ``-i`` - interval - replace -i 7d with your own time interval
+
+For example:
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -s 2018-01-02T15:04:05-07:00 -i 7d
+
+2. The command returns the task ID. You will need this ID for additional actions.
+
+3. If you want to run the repair only once, remove the `-i` argument.
+
+4. If you want to run this command immediately, but still want the repair to repeat, keep the interval argument (``-i``), but remove the start-date (``-s``).
+
+Schedule an ad-hoc repair
+.........................
+
+An ad-hoc repair runs immediately and does not repeat.
+This procedure shows the most frequently used repair command.
+Additional parameters can be used. Refer to the :ref:`sctool Reference <sctool-repair-parameters>`.
+
+**Procedure**
+
+1. Run the following command, replacing the -c argument with your cluster name:
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster
+
+2. The command returns the task ID. You will need this ID for additional actions.
+
+Repair faster or slower
+.......................
+
+When scheduling repair, you may specify ``--intensity`` flag, the intensity meaning is:
+
+* For values > 1 intensity specifies the number of segments repaired by Scylla in a single repair command. Higher values result in higher speed and may increase cluster load.
+* For values < 1 intensity specifies what percent of node's shards repaired in parallel.
+* For intensity equal to 1 it will repair one segment in each repair command on all shards in parallel.
+* For zero intensity it uses limits specified in Scylla Manager `configuration <../configuration-file#repair-settings>`_.
+
+ Please note that this only works with versions that are **not** :doc:`row-level-repair enabled </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+**Example**
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --intensity 16
+
+.. _manager-2.1-reschedule-a-repair:
+
+Reschedule a Repair
+-------------------
+
+You can change the run time of a scheduled repair using the update repair command.
+The new time you set replaces the time which was previously set.
+This command requires the task ID, which was generated when you set the repair.
+This can be retrieved using the command sctool :ref:`task list <sctool-task-list>`.
+
+This example updates a task to run in 3 hours instead of whatever time it was supposed to run.
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd -s now+3h
+
+To start a scheduled repair immediately, run the following command inserting the task id and cluster name:
+
+.. code-block:: none
+
+ sctool task start repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+
+Pause a Repair
+--------------
+
+Pauses a specified task, provided it is running.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``. To start the task again, see `Resume a Repair`_.
+
+.. code-block:: none
+
+ sctool task stop repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+Resume a Repair
+---------------
+
+Restart a repair that is currently in the paused state.
+To start running a repair which is scheduled, but is currently not running, use the task update command.
+See `Reschedule a Repair`_.
+You will need the task ID for this action. This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task start repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
+
+Delete a Repair
+---------------
+
+This action removes the repair from the task list.
+Once removed, you cannot resume the repair.
+You will have to create a new one.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task delete repair/143d160f-e53c-4890-a9e7-149561376cfd -c prod-cluster
diff --git a/docs/operating-scylla/manager/2.1/restore-a-backup.rst b/docs/operating-scylla/manager/2.1/restore-a-backup.rst
--- a/docs/operating-scylla/manager/2.1/restore-a-backup.rst
+++ b/docs/operating-scylla/manager/2.1/restore-a-backup.rst
@@ -0,0 +1,348 @@
+================
+Restore a Backup
+================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+This document provides information on how to restore data from backups that were taken using the Scylla Manager.
+
+There are two restore scenarios:
+
+#. Backup to the same topology cluster.
+ For example, restore data to the same source cluster.
+#. Backup to a different topology cluster.
+ For example, restore data to a smaller or bigger cluster, a cluster with a different rack or DC topology, or different token distribution.
+
+**Workflow**
+
+#. `Prepare for restore`_
+#. `Upload data to Scylla`_
+
+Prepare for restore
+===================
+
+No matter which backup scenario you are using, the procedures in this workflow apply.
+
+**Workflow**
+
+#. `Make sure Scylla cluster is up`_
+#. `Install Scylla Manager`_
+#. `Register the cluster with the Scylla Manager`_
+#. `Identify relevant snapshot`_
+#. `Restore the schema`_
+
+Make sure Scylla cluster is up
+------------------------------
+
+Make sure that your Scylla cluster is up and that there are no issues with networking, disk space, or memory.
+If you need help, you can check official documentation on :doc:`operational procedures for cluster management </operating-scylla/procedures/cluster-management/index>`.
+
+Install Scylla Manager
+----------------------
+
+You need a working Scylla Manager setup to list backups. If you don't have it installed, please follow official instructions on `how to install Scylla Manager <../install/>`_ first.
+
+Nodes must have access to the locations of the backups as per instructions in the official documentation for :ref:`installing Scylla Manager Agent <manager-2.1-prepare-nodes-for-backup>`.
+
+Register the cluster with the Scylla Manager
+--------------------------------------------
+
+This section only applies to situations where a registered cluster that was originally used for the backup is missing from the Scylla Manager.
+In that case, a new cluster must be registered before you can access the backups created with the old one.
+This example demonstrates adding a cluster named "cluster1" with initial node IP 18.185.31.99, instructs Scylla Manager not to schedule a default repair, and forcing uuid of the new cluster to ebec29cd-e768-4b66-aac3-8e8943bcaa76:
+
+ .. code-block:: none
+
+ sctool cluster add --host 18.185.31.99 --name cluster1 --without-repair -id ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ __
+ / \ Cluster added! You can set it as default, by exporting its name or ID as env variable:
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=ebec29cd-e768-4b66-aac3-8e8943bcaa76
+ | | $ export SCYLLA_MANAGER_CLUSTER=cluster1
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c cluster1
+ \___/ $ sctool task list -c cluster1
+
+Cluster is created, and we can proceed to list old backups.
+If the uuid of the old cluster is lost, there is a workaround with ``--all-clusters`` parameter.
+In that case, just register the cluster and proceed to the next step.
+
+Identify relevant snapshot
+--------------------------
+
+**Procedure**
+
+#. List all available backups and choose the one you would like to restore.
+ Run: :ref:`sctool backup list <sctool-backup-list>`, to lists all backups for the cluster.
+ This command will list backups only created with provided cluster (``-c clust1``).
+ If you don't have uuid of the old cluster, you can use ``--all-clusters`` to list all backups from all clusters that are available in the target location:
+
+ .. code-block:: none
+
+ sctool backup list -c cluster1 --all-clusters -L s3:backup-bucket
+ Cluster: 7313fda0-6ebd-4513-8af0-67ac8e30077b
+
+ Snapshots:
+ - sm_20200513131519UTC (563.07GiB)
+ - sm_20200513080459UTC (563.07GiB)
+ - sm_20200513072744UTC (563.07GiB)
+ - sm_20200513071719UTC (563.07GiB)
+ - sm_20200513070907UTC (563.07GiB)
+ - sm_20200513065522UTC (563.07GiB)
+ - sm_20200513063046UTC (563.16GiB)
+ - sm_20200513060818UTC (534.00GiB)
+ Keyspaces:
+ - system_auth (4 tables)
+ - system_distributed (2 tables)
+ - system_schema (12 tables)
+ - system_traces (5 tables)
+ - user_data (100 tables)
+
+ Here, for example, we have eight different snapshots to choose from.
+ Snapshot tags encode the date they were taken in UTC time zone.
+ For example, ``sm_20200513131519UTC`` was taken on 13/05/2020 at 13:15 and 19 seconds UTC.
+ The data source for the listing is the cluster backup locations.
+ Listing may take some time, depending on how big the cluster is and how many backups there are.
+
+.. _restore-backup-restore-schema:
+
+Restore the schema
+------------------
+
+Scylla Manager 2.1 can store schema with your backup.
+To extract schema files for each keyspace from the backup, please refer to the official documentation for `extracting schema from the backup <../../2.1/extract-schema-from-backup>`_. For convenience, here is the continuation of our example with the list of steps for restoring schema:
+
+#. Download schema from the backup store to the current dir. It's in the first line of the ``backup_files.out`` output:
+
+ .. code-block:: none
+
+ sctool backup files --cluster my-cluster -L s3:backup-bucket -T sm_20200513104924UTC --with-version | head -n 1 | xargs -n2 aws s3 cp
+ download: s3://backup-bucket/backup/schema/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz to ./task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz
+
+#. Extract schema files by decompressing archive:
+
+ .. code-block:: none
+
+ mkdir ./schema
+ tar -xf task_001ce624-9ac2-4076-a502-ec99d01effe4_tag_sm_20200513104924UTC_schema.tar.gz -C ./schema
+ ls ./schema
+ system_auth.cql system_distributed.cql system_schema.cql system_traces.cql user_data.cql
+
+
+* If you do *not* have the schema file available, you can `extract the schema from system table <https://manager.docs.scylladb.com/branch-2.2/restore/extract-schema-from-metadata.html>`_.
+
+Full schema restore procedure can be found at :ref:`steps 1 to 5 <restore-procedure>`.
+For convenience, here is the list of steps for our example (WARNING: these can be destructive operations):
+
+#. Run the ``nodetool drain`` command to ensure the data is flushed to the SSTables.
+
+#. Shut down the node:
+
+ .. code-block:: none
+
+ sudo systemctl stop scylla-server
+
+#. Delete all files in the commitlog:
+
+ .. code-block:: none
+
+ sudo rm -rf /var/lib/scylla/commitlog/*
+
+#. Delete all the files in the user_data.data_* tables (only files, not directories):
+
+ .. code-block:: none
+
+ sudo rm -f /var/lib/scylla/data/user_data/data_0-6e856600017f11e790f4000000000000/*
+
+If cluster is added with CQL credentials (see :doc:`Add Cluster <add-a-cluster>` for reference) Scylla Manager would backup schema in CQL format.
+To obtain CQL schema from a particular backup, use ``sctool backup files`` command, for example:
+
+.. code-block:: none
+
+ sctool backup files -c my-cluster -L s3:backups -T sm_20191210145143UTC
+
+The first output line is a path to schemas archive, for example:
+
+.. code-block:: none
+
+ s3://backups/backup/schema/cluster/ed63b474-2c05-4f4f-b084-94541dd86e7a/task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz ./
+
+This archive contains a single CQL file for each keyspace in the backup.
+
+.. code-block:: none
+
+ tar -ztvf task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz
+ -rw------- 0/0 2366 2020-05-08 14:38 system_auth.cql
+ -rw------- 0/0 931 2020-05-08 14:38 system_distributed.cql
+ -rw------- 0/0 11557 2020-05-08 14:38 system_schema.cql
+ -rw------- 0/0 4483 2020-05-08 14:38 system_traces.cql
+
+To restore the schema, you need to execute the files with cqlsh command.
+
+**Procedure**
+
+#. Download schema archive
+
+ .. code-block:: none
+
+ aws s3 cp s3://backups/backup/schema/cluster/ed63b474-2c05-4f4f-b084-94541dd86e7a/task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz ./
+
+#. Extract CQL files from archive
+
+ .. code-block:: none
+
+ tar -xzvf task_287791d9-c257-4850-aef5-7537d6e69d90_tag_sm_20200506115612UTC_schema.tar.gz
+
+#. Copy CQL files for desired keyspaces to a cluster node
+#. On node execute CQL files using cqlsh
+
+ .. code-block:: none
+
+ cqlsh -f my_keyspace.cql
+
+Upload data to Scylla
+=====================
+
+You can either upload the data:
+
+* `To the same cluster`_: with the same nodes, topology, and the same token distribution **OR**
+* `To a new cluster`_: of any number of nodes
+
+
+To the same cluster
+-------------------
+
+List the backup files
+.....................
+
+List the backup files needed on each node and save the list to a file.
+
+If you are listing old backups from the new cluster use ``--all-clusters`` parameter.
+
+.. code-block:: none
+
+ sctool backup files -c cluster1 --snapshot-tag sm_20200513131519UTC \
+ --with-version \
+ --location s3:backup-bucket \
+ > backup_files.out
+
+Snapshot information is now stored in ``backup_files.out`` file.
+Each line of the ``backup_files.out`` file contains mapping between the path to the SSTable file in the backup bucket, and it's mapping to keyspace/table.
+If Scylla Manager is configured to store database schemas with the backups, then the first line in the file listing is the path to the schema archive.
+
+For example:
+
+.. code-block:: none
+
+ s3://backup-bucket/backup/sst/cluster/7313fda0-6ebd-4513-8af0-67ac8e30077b/dc/AWS_EU_CENTRAL_1/node/92de78b1-6c77-4788-b513-2fff5a178fe5/keyspace/user_data/table/data_65/a2667040944811eaaf9d000000000000/la-72-big-Index.db user_data/data_65-a2667040944811eaaf9d000000000000
+
+Path contains metadata, for example:
+
+* Cluster ID - 7313fda0-6ebd-4513-8af0-67ac8e30077b
+* Data Center - AWS_EU_CENTRAL_1
+* Directory - /var/lib/scylla/data/user_data/data_65-a2667040944811eaaf9d000000000000/
+* Keyspace - user_data
+
+.. code-block:: none
+
+ sctool backup files -c prod-cluster --snapshot-tag sm_20191210145027UTC \
+ --with-version > backup_files.out
+
+Each line describes a backed-up file and where it should be downloaded. For example
+
+.. code-block:: none
+
+ s3://backups/backup/sst/cluster/1d781354-9f9f-47cc-ad45-f8f890569656/dc/dc1/node/ece658c2-e587-49a5-9fea-7b0992e19607/keyspace/auth_service/table/roles/5bc52802de2535edaeab188eecebb090/mc-2-big-CompressionInfo.db auth_service/roles-5bc52802de2535edaeab188eecebb090
+
+This file has to be copied to:
+
+* Cluster - 1d781354-9f9f-47cc-ad45-f8f890569656
+* Data Center - dc1
+* Node - ece658c2-e587-49a5-9fea-7b0992e19607
+* Directory - /var/lib/scylla/data/auth_service/roles-5bc52802de2535edaeab188eecebb090/upload
+
+Download the backup files
+.........................
+
+This step must be executed on **each node** in the cluster.
+
+#. Copy ``backup_files.out`` file as ``/tmp/backup_files.out`` on the node.
+
+#. Run ``nodetool status`` to get to know the node ID.
+
+#. Download data into table directories.
+ As the file is kept in S3 so we can use S3 CLI to download it (this step may be different with other storage providers).
+ Grep can be used to filter specific files to restore.
+ With node UUID we can filter files only for a single node.
+ With a keyspace name, we can filter files only for a single keyspace.
+
+ .. code-block:: none
+
+ cd /var/lib/scylla/data
+
+ # Filter only files for a single node.
+ grep ece658c2-e587-49a5-9fea-7b0992e19607 /tmp/backup_files.out | xargs -n2 aws s3 cp
+
+#. Make sure that all files are owned by the Scylla user and group.
+ We must ensure that permissions are right after copy:
+
+ .. code-block:: none
+
+ sudo chown -R scylla:scylla /var/lib/scylla/data/user_data/
+
+#. Start the Scylla nodes:
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-server
+
+Repair
+......
+
+After performing the above on all nodes, repair the cluster with Scylla Manager Repair.
+This makes sure that the data is consistent on all nodes and between each node.
+
+To a new cluster
+----------------
+
+In order to restore a backup to a cluster that has a different topology, you have to use an external tool called :doc:`sstableloader </operating-scylla/procedures/cassandra-to-scylla-migration-process>`.
+This procedure is much slower than restoring to the same topology cluster.
+
+**Procedure**
+
+#. Start up the nodes if they are not running after schema restore:
+
+ .. code-block:: none
+
+ sudo systemctl start scylla-server
+
+#. List all the backup files and save the list to a file.
+
+ Use ``--all-clusters`` if you are restoring from the cluster that no longer exists.
+
+ .. code-block:: none
+
+ sctool backup files -c cluster1 --snapshot-tag sm_20200513131519UTC --location s3:backup-bucket > backup_files.out
+
+#. Copy ``backup_files.out`` file as ``/tmp/backup_files.out`` on the host where ``sstableloader`` is installed.
+
+#. Download all files created during backup into temporary location:
+
+ .. code-block:: none
+
+ mkdir snapshot
+ cd snapshot
+ # Create temporary directory structure.
+ cat /tmp/backup_files.out | awk '{print $2}' | xargs mkdir -p
+ # Download snapshot files.
+ cat /tmp/backup_files.out | xargs -n2 aws s3 cp
+
+#. Execute the following command for each table by providing a list of node IP addresses and path to sstable files on node that has sstableloader installed:
+
+ .. code-block:: none
+
+ # Loads table user_data.data_0 into four node cluster.
+ sstableloader -d '35.158.14.221,18.157.98.72,3.122.196.197,3.126.2.205' ./user_data/data_0 --username scylla --password <password>
+
+After tables are restored, verify the validity of your data by running queries on your database.
diff --git a/docs/operating-scylla/manager/2.1/sctool.rst b/docs/operating-scylla/manager/2.1/sctool.rst
--- a/docs/operating-scylla/manager/2.1/sctool.rst
+++ b/docs/operating-scylla/manager/2.1/sctool.rst
@@ -0,0 +1,1607 @@
+=====================
+Sctool CLI Reference
+=====================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+This document is a complete reference for the sctool CLI.
+The commands are in alphabetical order.
+
+
+About sctool
+------------
+
+``sctool`` is a Command Line Interface (CLI) for the Scylla Manager server.
+The server communicates with managed Scylla clusters and performs cluster-wide operations such as automatic repair and backup.
+
+**Usage**
+
+.. code-block:: none
+
+ sctool command [flags] [global flags]
+
+Global flags
+============
+
+* ``--api-cert-file <path>`` - specifies the path to HTTPS client certificate used to access the Scylla Manager server
+* ``--api-key-file <path>`` - specifies the path to HTTPS client key used to access the Scylla Manager server
+* ``--api-url URL`` - URL of Scylla Manager server (default "http://localhost:8889/api/v1")
+* ``-c, --cluster <cluster_name>`` - Specifies the target cluster name or ID
+* ``-h, --help`` - Displays help for commands. Use ``sctool [command] --help`` for help about a specific command.
+
+Environment variables
+=====================
+
+sctool uses the following environment variables:
+
+* `SCYLLA_MANAGER_CLUSTER` - if set, specifies the default value for the ``-c, --cluster`` flag, in commands that support it.
+* `SCYLLA_MANAGER_API_URL` - if set, specifies the default value for the ``--api-url`` flag; it can be useful when using sctool with a remote Scylla Manager server.
+
+The environment variables may be saved in your ``~/.bashrc`` file so that the variables are set after login.
+
+Backup clusters
+---------------
+
+The backup commands allow you to: create a backup (ad-hoc or scheduled), list the contents of a backup, and list the backups of a cluster.
+A Scylla cluster must be added (`cluster add`_) before management tasks can be initiated.
+
+.. code-block:: none
+
+ sctool backup <command> [global flags] [parameters]
+
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `backup`_
+ - Schedule a backup (ad-hoc or scheduled).
+ * - `backup files`_
+ - List contents of a given backup.
+ * - `backup list`_
+ - List backups of a given cluster.
+ * - `backup delete`_
+ - Deletes one of available snapshots.
+
+.. _sctool-backup:
+
+backup
+======
+
+The backup command allows you to schedule or run ad-hoc cluster backup.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup --cluster <id|name> --location <list of locations> [--dc <list>]
+ [--dry-run] [--force] [--interval <time-unit>]
+ [--keyspace <list of glob patterns to find keyspaces>]
+ [--num-retries <times to rerun a failed task>]
+ [--rate-limit <list of rate limits>] [--retention <number of backups to store>]
+ [--show-tables]
+ [--snapshot-parallel <list of parallelism limits>] [--start-date <date>]
+ [--upload-parallel <list of parallelism limits>] [global flags]
+
+.. _sctool-backup-parameters:
+
+backup parameters
+.................
+
+In addition to the `Global flags`_, backup takes the following parameters:
+
+
+=====
+
+``--dc <list of glob patterns>``
+
+A comma-separated list of datacenter glob patterns, e.g. 'dc1,!otherdc*' used to specify the DCs to include or exclude from backup, separated by a comma.
+This can also include glob patterns.
+
+.. include:: _common/glob.rst
+
+=====
+
+``--dry-run``
+
+Validates and prints backup information without actually scheduling a backup.
+
+=====
+
+``--force``
+
+Forces backup to skip database validation and schedules a backup even if there are no matching keyspaces/tables.
+
+=====
+
+``-i, --interval <time-unit>``
+
+Scheduled Intervals for backups to repeat every X time, where X can be:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+
+For example: ``-i 3d2h10m``
+
+**Default: 0** - this means the task does not recur.
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma used to include or exclude keyspaces from the backup.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[dc:]<provider>:<name>`` ex. ``s3:my-bucket``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` at the moment is ``s3``.
+
+=====
+
+``-r, --num-retries <times to rerun a failed task>``
+
+The number of times a scheduled task will retry to run before failing.
+
+**Default: 3**
+
+=====
+
+``--rate-limit <list of rate limits>``
+
+Limits the upload rate (as expressed in megabytes (MB) per second), which a snapshot file can be uploaded from a Scylla node to its backup destination.
+For example, an S3 bucket.
+You can set limits for more than one DC using a comma-separated list expressed in the format ``[<dc>:]<limit>``.
+The <dc>: part is optional and is only needed when different datacenters require different upload limits.
+
+**Default: 100**
+
+=====
+
+``--retention <number of backups to store>``
+
+The number of backups to store.
+Once this number is reached, the next backup which comes in from this destination will initiate a purge of the oldest backup.
+
+**Default: 3**
+
+=====
+
+``--show-tables``
+
+Prints table names together with keyspace.
+
+=====
+
+``--snapshot-parallel <list of parallelism limits>``
+
+A comma-separated list of snapshot parallelism limits in the format ``[<dc>:]<limit>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and allows for specifying different limits in selected datacenters.
+If The <dc>: part is not set, the limit is global (e.g. 'dc1:2,5'). The runs are parallel in ``n`` nodes (2 in dc1 (as shown in the example) and ``n`` nodes in all the other datacenters.
+
+=====
+
+``-s, --start-date <date>``
+
+Specifies the task start date expressed in the RFC3339 format or ``now[+duration]``, e.g. ``now+3d2h10m``, valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+**Default: now**
+
+=====
+
+``--upload-parallel <list of parallelism limits>``
+
+A comma-separated list of upload parallelism limits in the format ``[<dc>:]<limit>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and allows for specifying different limits in selected datacenters.
+If The <dc>: part is not set, the limit is global (e.g. 'dc1:2,5'). The runs are parallel in ``n`` nodes (2 in dc1 (as shown in the example) and ``n`` nodes in all the other datacenters.
+
+=====
+
+Example: backup
+................
+
+This example backs up the entire cluster named prod-cluster.
+The backup begins on December 9, 2019 at 16:05 and will repeat at this time every 24 hours.
+The backup is stored in s3 in a directory named ``my-backups``.
+Additional examples are available in `Backup Scylla Clusters <../backup/>`_
+
+.. code-block:: none
+
+ sctool backup -c prod-cluster -s '2019-12-09T15:16:05Z' -i 24h -L 's3:my-backups'
+ backup/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+.. _sctool-backup-list:
+
+backup list
+===========
+
+These commands allow you to list backups of a given cluster.
+
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup list [--all clusters] [--keyspace <list of glob patterns to find keyspaces>] [--location <list of backup locations>]
+ [--max-date <date>] [--min-date <date>] [--show-tables][global flags]
+
+backup list parameters
+......................
+
+In addition to the `Global flags`_, backup list takes the following parameters:
+
+=====
+
+``--all-clusters``
+
+Shows backups for all clusters
+
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``--max-date <date>``
+
+Specifies maximal snapshot date expressed in RFC3339 form or ``now[+duration]``.
+For example: ``now+3d2h10m`` Valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+=====
+
+``--min-date <date>``
+
+Specifies minimal snapshot date expressed in RFC3339 form or ``now[+duration]``.
+For example: ``now+3d2h10m`` Valid units are:
+
+* ``d`` - days
+* ``h`` - hours
+* ``m`` - minutes
+* ``s`` - seconds
+* ``now`` - happens immediately
+
+=====
+
+``--show-tables``
+
+Prints table names together with keyspace.
+
+=====
+
+Example: backup list
+....................
+
+
+.. code-block:: none
+
+ sctool backup list -c prod-cluster --show-tables
+ Snapshots:
+ - sm_20191210145143UTC
+ - sm_20191210145027UTC
+ - sm_20191210144833UTC
+ Keyspaces:
+ - system_auth (role_members, roles)
+ - system_distributed (view_build_status)
+ - system_traces (events, node_slow_log, node_slow_log_time_idx, sessions, sessions_time_idx)
+ - test_keyspace_dc1_rf2 (void1)
+ - test_keyspace_dc1_rf3 (void1)
+ - test_keyspace_dc2_rf2 (void1)
+ - test_keyspace_dc2_rf3 (void1)
+ - test_keyspace_rf2 (void1)
+ - test_keyspace_rf3 (void1)
+
+backup files
+============
+
+This command allows you to list the content of a given backup.
+This command lists files that were uploaded during the backup procedure.
+It outputs the remote paths of files together with keyspace/table information separated by a delimiter that you provide.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup files [--all clusters] [--keyspace <list of glob patterns to find keyspaces>]
+ [--location <list of backup locations>] [global flags]
+
+backup files parameters
+.......................
+
+In addition to the `Global flags`_, backup files add takes the following parameters:
+
+=====
+
+``--all-clusters``
+
+Shows backups for all clusters
+
+=====
+
+``-d, --delimiter <delimiter-character>``
+
+Dictates which character will be used as whitespace between remote file path and information about keyspace and table.
+
+**Default: '\t'**
+
+=====
+
+``-K, --keyspace <list of glob patterns to find keyspaces>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to place the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``-T, --snapshot-tag <tag>``
+
+Snapshot tag as read from the backup listing
+
+=====
+
+Example: backup files
+.....................
+
+.. code-block:: none
+
+ sctool backup files --keyspace system_auth
+
+The command output has the following format:
+
+.. code-block:: none
+
+ <provider>://<bucket-name>/backup/sst/cluster/<cluster-id>/dc/<dc-id>/
+ node/<node-id>/keyspace/<keyspace-name>/table/<table-name>/<table-uuid>/
+ <filename><delimiter><keyspace-name>/<table-name>
+
+Example:
+
+.. code-block:: none
+
+ s3://backups/backup/sst/cluster/7d8f190f-c98d-4a06-8bb5-ae96633ee69a/dc/dc2/
+ node/f3c6386b-6d54-4546-a2e8-627fff62d3af/keyspace/system_sec/table/roles/5bc52802de2535edaeab188eecebb090/
+ mc-2-big-TOC.txt system_sec/table
+
+From this information we know the following:
+
+* Provider - s3
+* Bucket name - backups
+* Cluster ID - 7d8f190f-c98d-4a06-8bb5-ae96633ee69a
+* DC - DC2
+* Node - f3c6386b-6d54-4546-a2e8-627fff62d3af
+* Keyspace - system_sec
+* Table name - roles
+* Table UUID - 5bc52802de2535edaeab188eecebb090
+* File name - mc-2-big-TOC.txt
+* Delimiter - whitespace character (ie ' ')
+* Keyspace / table name - system_sec/table
+
+See `Restore <restore>`_ on information how to use these files to restore a backup.
+
+backup delete
+=============
+
+This command allows you to delete files that were uploaded during the backup procedure.
+Deduplicated files are persisted unless their reference count drops to zero.
+
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool backup delete --snapshot-tag <snapshot tag> [--location <list of backup locations>] [global flags]
+
+backup delete parameters
+........................
+
+In addition to the `Global flags`_, backup delete takes the following parameters:
+
+=====
+
+``-L, --location <list of backup locations>``
+
+Specifies where to look for the backup in the format ``[<dc>:]<provider>:<name>``.
+More than one location can be stated in a comma-separated list.
+The <dc>: part is optional and is only needed when different datacenters are being used to upload data to different locations.
+``name`` must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.
+The only supported storage ``provider`` is s3.
+
+=====
+
+``-T, --snapshot-tag <tag>``
+
+Snapshot tag as read from the backup listing.
+
+=====
+
+Example: backup delete
+......................
+
+.. code-block:: none
+
+ sctool backup delete --snapshot-tag sm_20200526115228UTC
+
+The command does not output anything unless an error happens.
+
+Managing clusters
+-----------------
+
+The cluster commands allow you to add, delete, list, and update clusters.
+A Scylla cluster must be added (`cluster add`_) before management tasks can be initiated.
+
+.. code-block:: none
+
+ sctool cluster <command> [flags] [global flags]
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `cluster add`_
+ - Add a cluster to manager.
+ * - `cluster delete`_
+ - Delete a cluster from manager.
+ * - `cluster list`_
+ - Show managed clusters.
+ * - `cluster update`_
+ - Modify a cluster.
+
+.. _sctool-cluster-add:
+
+cluster add
+===========
+
+This command adds the specified cluster to the manager.
+Once a Scylla cluster is added, a weekly repair task is also added.
+
+Before continuing, make sure the cluster that you want to add is prepared for it,
+see `Add a cluster to Scylla Manager <../add-a-cluster>`_ for instructions.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster add --host <node IP> --auth-token <token>[--name <alias>][--without-repair][global flags]
+
+cluster add parameters
+......................
+
+In addition to the `Global flags`_, cluster add takes the following parameters:
+
+=====
+
+.. include:: _common/cluster-params.rst
+
+=====
+
+Example: cluster add
+....................
+
+This example is only the command that you use to add the cluster to Scylla Manager, not the entire procedure for adding a cluster.
+The procedure is detailed in `Add a cluster to Scylla Manager <../add-a-cluster>`_.
+
+.. code-block:: none
+
+ sctool cluster add --host 34.203.122.52 --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+ c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ __
+ / \ Cluster added! You can set it as default, by exporting env variable.
+ @ @ $ export SCYLLA_MANAGER_CLUSTER=c1bbabf3-cad1-4a59-ab8f-84e2a73b623f
+ | | $ export SCYLLA_MANAGER_CLUSTER=prod-cluster
+ || |/
+ || || Now run:
+ |\_/| $ sctool status -c prod-cluster
+ \___/ $ sctool task list -c prod-cluster
+
+Example (IPv6):
+
+.. code-block:: none
+
+ sctool cluster add --host 2a05:d018:223:f00:971d:14af:6418:fe2d --auth-token "6Es3dm24U72NzAu9ANWmU3C4ALyVZhwwPZZPWtK10eYGHJ24wMoh9SQxRZEluWMc0qDrsWCCshvfhk9uewOimQS2x5yNTYUEoIkO1VpSmTFu5fsFyoDgEkmNrCJpXtfM" --name prod-cluster
+
+cluster delete
+==============
+
+This command deletes the specified cluster from the manager.
+Note that there is no confirmation or warning to confirm.
+If you deleted the cluster by mistake, you will need to add it again.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster delete --cluster <id|name> [global flags]
+
+.. note:: If you are removing the cluster from Scylla Manager and you are using Scylla Monitoring, remove the target from Prometheus Target list in the prometheus/scylla_manager_servers.yml file.
+
+
+cluster delete parameters
+.........................
+
+In addition to `Global flags`_, cluster delete takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: cluster delete
+.......................
+
+.. code-block:: none
+
+ sctool cluster delete -c prod-cluster
+
+cluster list
+============
+
+Lists the managed clusters.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster list [global flags]
+
+cluster list parameters
+.......................
+
+cluster list takes the `Global flags`_.
+
+Example: cluster list
+.....................
+
+.. code-block:: none
+
+ sctool cluster list
+ ╭──────────────────────────────────────┬──────────────╮
+ │ ID │ Name │
+ ├──────────────────────────────────────┼──────────────┤
+ │ db7faf98-7cc4-4a08-b707-2bc59d65551e │ prod-cluster │
+ ╰──────────────────────────────────────┴──────────────╯
+
+.. _sctool-cluster-update:
+
+cluster update
+==============
+
+This command modifies managed cluster parameters.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool cluster update --cluster <id|name> [--host <node IP>] [--auth-token <token>] [--name <alias>] [--without-repair] [global flags]
+
+
+cluster update parameters
+.........................
+
+In addition to the `Global flags`_, cluster update takes all the `cluster add parameters`_.
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+.. include:: _common/cluster-params.rst
+
+=====
+
+Example: cluster update
+.......................
+
+In this example, the cluster named ``cluster`` has been renamed to ``prod-cluster``.
+
+.. code-block:: none
+
+ sctool cluster update --prod-cluster cluster --name prod-cluster
+
+Scheduling repairs
+------------------
+
+repair
+======
+
+The repair commands allow you to schedule repairs for a specified cluster.
+
+.. code-block:: none
+
+ sctool repair --cluster <id|name> [--dc <list of glob patterns>] [--dry-run]
+ [--fail-fast] [--force] [--host <node IP>] [--interval <time between task runs>]
+ [--intensity <float>]
+ [--keyspace <list of glob patterns>] [--num-retries <times to rerun a failed task>]
+ [--start-date <now+duration|RFC3339>]
+ [--token-ranges <pr|npr|all>] [--with-hosts <list of node IPs>][global flags]
+
+.. _sctool-repair-parameters:
+
+repair parameters
+.................
+
+In addition to `Global flags`_, repair takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--dc <list of glob patterns>``
+
+List of data centers to be repaired, separated by a comma.
+This can also include glob patterns.
+
+.. include:: _common/glob.rst
+
+**Example**
+
+Given the following data centers: *us-east-1*, *us-east-2*, *us-west-1*, *us-west-2*.
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Parameter
+ - Selects
+ * - ``--dc us-east-1,us-west-2``
+ - *us-east-1*, *us-west-2*
+ * - ``--dc 'us-east-*'``
+ - *us-east-1*, *us-east-2*
+ * - ``--dc '*','!us-east-'``
+ - *us-west-1*, *us-west-2*
+
+**Default:** everything - all data centers
+
+=====
+
+``--dry-run``
+
+Validates and displays repair information without actually scheduling the repair.
+This allows you to display what will happen should the repair run with the parameters you set.
+
+**Example**
+
+Given the following keyspaces:
+
+* system_auth
+* system_distributed
+* system_traces
+* test_keyspace_dc1_rf2, test_keyspace_dc1_rf3, and test_keyspace_dc2_rf2
+* keyspace_dc2_rf3
+* test_keyspace_rf2 and test_keyspace_rf3
+
+The following command will run a repair on all keyspaces **except** for test_keyspace_dc1_rf2 in dry-run mode.
+
+
+.. code-block:: none
+
+ sctool repair --dry-run -K '*,!test_keyspace_dc1_rf2'
+ NOTICE: dry run mode, repair is not scheduled
+
+ Data Centers:
+ - dc1
+ - dc2
+ Keyspace: system_auth
+ (all tables)
+ Keyspace: system_distributed
+ (all tables)
+ Keyspace: system_traces
+ (all tables)
+ Keyspace: test_keyspace_dc1_rf3
+ (all tables)
+ Keyspace: test_keyspace_dc2_rf2
+ (all tables)
+ Keyspace: test_keyspace_dc2_rf3
+ (all tables)
+ Keyspace: test_keyspace_rf2
+ (all tables)
+ Keyspace: test_keyspace_rf3
+ (all tables)
+
+**Example with error**
+
+.. code-block:: none
+
+ sctool repair -K 'system*.bla' --dry-run -c bla
+ NOTICE: dry run mode, repair is not scheduled
+
+ Error: API error (status 400)
+ {
+ "message": "no matching units found for filters, ks=[system*.*bla*]",
+ "trace_id": "b_mSOUoOSyqSnDtk9EANyg"
+ }
+
+=====
+
+``--fail-fast``
+
+Stops the repair process on the first error.
+
+**Default:** False
+
+=====
+
+``--force``
+
+Forces the repair to skip database validation and schedules a repair even if there aren't any matching keyspaces/tables.
+This means that if the glob patterns match nothing, a repair will still run.
+
+Default: False
+
+=====
+
+``--host <node IP>``
+
+Host to repair, you may use that to repair given host with other hosts (--with-hosts), you may also want to specify token ranges to repair (--token-ranges).
+You can use either an IPv4 or IPv6 address.
+
+=====
+
+``--intensity <float>``
+
+Repair speed, higher values result in higher speed and may increase cluster load.
+Values in a range (0-1) result in lower speed and load.
+
+When intensity is below 1, the repair is executed only on the specified fraction of shards at the same time.
+Please note that this only works with versions that are not :doc:`row-level-repair enabled </upgrade/upgrade-manager/upgrade-guide-from-2.x.a-to-2.y.b/upgrade-row-level-repair>`.
+
+**Default:** 0
+
+=====
+
+``-K, --keyspace <list of glob patterns>``
+
+A list of glob patterns separated by a comma.
+The patterns match keyspaces and tables, when you write the pattern,
+separate the keyspace name from the table name with a dot (*KEYSPACE.TABLE*).
+
+.. include:: _common/glob.rst
+
+**Example**
+
+Given the following tables:
+
+* *shopping_cart.cart*
+* *orders.orders_by_date_2018_11_01*
+* *orders.orders_by_date_2018_11_15*
+* *orders.orders_by_date_2018_11_29*
+* *orders.orders_by_date_2018_12_06*
+
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Parameter
+ - Selects
+ * - ``-K '*'``
+ - *everything - all tables in all keyspaces*
+ * - ``-K shopping_cart``
+ - *shopping_cart.cart*
+ * - ``-K '*,!orders'``
+ - *shopping_cart.cart*
+ * - ``-K orders.'orders.2018_11_'``
+ - *orders.orders_by_date_2018_11_01*
+ *orders.orders_by_date_2018_11_15*
+ *orders.orders_by_date_2018_11_29*
+ * - ``-K 'orders.*2018_1?_2?'``
+ - *orders.orders_by_date_2018_11_29*
+ * - ``-K 'orders.*2018_11?[19]'``
+ - *orders.orders_by_date_2018_11_01*
+ *orders.orders_by_date_2018_11_29*
+
+**Default:** everything - all tables in all keyspaces
+
+=====
+
+``--token-ranges <pr|npr|all>``
+
+Dictates which token range is used for the repair.
+There are three to choose from:
+
+* ``pr``- restricts the repair to the Primary token Range. This is a token range where the node is the first replica in the ring. It is important that if you choose this option to make sure it runs on **every** node in the cluster in order to repair the entire ring.
+* ``npr``- runs the repair on the non-primary token range.
+* ``all``- repairs all ranges, primary and non-primary.
+
+**Default:** pr
+
+.. note:: ``--token-ranges`` requires ``--host`` or ``--with-hosts`` to also be used.
+
+=====
+
+``--with-hosts <list of node IPs>``
+
+List of hosts to repair with separated by a comma.
+When the repair runs the repair compares the ``--host`` with the ``--with-hosts``.
+
+Use **caution** with this flag.
+It disables the built-in Scylla mechanism for repair and uses only the IP or hostname you set here.
+If there is a situation where there is missing data in the --with-host cluster, it will be deleted from the subsequent clusters.
+You can use either an IPv4 or IPv6 address.
+
+=====
+
+.. include:: _common/task-params.rst
+
+=====
+
+Example: Schedule a repair
+..........................
+
+Repairs can be scheduled to run on selected keyspaces/tables, nodes, or datacenters.
+Scheduled repairs run every *n* days, depending on the frequency you set.
+A scheduled repair runs at the time you set it to run at.
+If no time is given, the repair runs immediately.
+Repairs can run once or can run at a set schedule based on a time interval.
+
+Repair cluster weekly
+^^^^^^^^^^^^^^^^^^^^^
+
+In this example, you create a repair task for a cluster named *prod-cluster*.
+The task begins on May 2, 2019 at 3:04 PM.
+It repeats every week at this time.
+As there are no datacenters or keyspaces listed, all datacenters and all data in the specified cluster are repaired.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -s 2019-05-02T15:04:05-07:00 --interval 7d
+
+The system replies with a repair task ID.
+You can use this ID to change the start time, stop the repair, or cancel the repair.
+
+.. code-block:: none
+
+ repair/3208ff15-6e8f-48b2-875c-d3c73f545410
+
+Repair datacenters in a region weekly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example repairs all datacenters starting with the name *dc-asia-*, such as *dc-asia-1*.
+The repair begins on September 15, 2018 at 7:00 PM (JST, for example) and runs every week.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --dc 'asia-*' -s 2018-09-15T19:00:05-07:00 --interval 7d
+
+Repair selected keyspaces/tables weekly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using glob patterns gives you additional flexibility in selecting both keyspaces and tables.
+This example repairs all tables in the *orders* keyspace starting with *2018_11_* prefix.
+The repair is scheduled to run on December 4, 2018 at 8:00 AM and will run after that point every week.
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster -K 'orders.2018_12_' -s 2018-12-04T08:00:05-07:00 --interval 7d
+
+Repair a specific host once
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By listing the host IP address, you run a repair only on the specified host.
+The argument ``--token-ranges all`` specifies that the repair will run on all token ranges (primary and secondary).
+
+Example (IPv4):
+
+.. code-block:: none
+
+ sctool repair -c prod-cluster --host 198.100.51.11 --token-ranges all
+
+Monitoring clusters
+-------------------
+
+.. _sctool_status:
+
+status
+======
+
+The status command is an extended version of ``nodetool status``.
+It can show status for all the managed clusters.
+The first column shows node status in :doc:`nodetool format </operating-scylla/nodetool-commands/status>`.
+The CQL column shows the CQL status, SSL indicator if SSL is enabled on a node, and time the check took.
+
+Available statuses are:
+
+* UP - Situation normal
+* DOWN - Failed to connect to host or CQL error
+* UNAUTHORISED - Wrong username or password - only if ``username`` is specified for cluster
+* TIMEOUT - Timeout
+
+The REST column shows the status of Scylla Manager Server to Scylla API communication and the time the check took.
+
+Available statuses are:
+
+* UP - Situation normal
+* DOWN - Failed to connect to host
+* HTTP XXX - HTTP failure and its status code
+* UNAUTHORISED - Wrong ``api-key`` specified for cluster or in :ref:`Scylla Manager Agent configuration file <manger-2.1-agent-configuration-file-auth-token>`
+* TIMEOUT - Timeout
+
+The status information is also available as a metric in the Scylla Monitoring Manager dashboard.
+The `healthcheck` task checks nodes every 15 seconds. The interval can be changed using `task update`_ command.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool status [global flags]
+
+status parameters
+..................
+
+status takes the `Global flags`_.
+
+Example: status
+................
+
+.. code-block:: none
+
+ sctool status
+ Cluster: prod-cluster (c1bbabf3-cad1-4a59-ab8f-84e2a73b623f)
+ Datacenter: eu-west
+ ╭────┬───────────────┬────────────┬──────────────┬──────────────────────────────────────╮
+ │ │ CQL │ REST │ Host │ Host ID │
+ ├────┼───────────────┼────────────┼──────────────┼──────────────────────────────────────┤
+ │ UN │ UP SSL (42ms) │ UP (52ms) │ 10.0.114.68 │ 45a7390d-d162-4daa-8bff-6469c9956f8b │
+ │ UN │ UP SSL (38ms) │ UP (88ms) │ 10.0.138.46 │ 8dad7fc7-5a82-4fbb-8901-f6f60c12342a │
+ │ UN │ UP SSL (38ms) │ UP (298ms) │ 10.0.196.204 │ 44eebe5b-e0cb-4e45-961f-4ad175592977 │
+ │ UN │ UP SSL (43ms) │ UP (159ms) │ 10.0.66.115 │ 918a52aa-cc42-43a4-a499-f7b1ccb53b18 │
+ ╰────┴───────────────┴────────────┴──────────────┴──────────────────────────────────────╯
+
+.. _sctool-managing-tasks:
+
+Managing tasks
+--------------
+
+The task command set allows you to schedule, start, stop and modify tasks.
+
+.. code-block:: none
+
+ sctool task <command> [flags] [global flags]
+
+**Subcommands**
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Subcommand
+ - Usage
+ * - `task delete`_
+ - Delete a task.
+ * - `task history`_
+ - Show run history of a task.
+ * - `task list`_
+ - Show available tasks and their last run status.
+ * - `task progress`_
+ - Show the task progress.
+ * - `task start`_
+ - Start executing a task.
+ * - `task stop`_
+ - Stop executing a task.
+ * - `task update`_
+ - Modify a task.
+
+task delete
+===========
+
+This command deletes a task from the manager.
+Note that a task can be disabled if you want to temporarily turn it off (see `task update`_).
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task delete <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task delete parameters
+......................
+
+In addition to the `Global Flags`_, task delete takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: task delete
+....................
+
+This example deletes the repair from the task list.
+You need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+Once the repair is removed, you cannot resume the repair.
+You will have to create a new one.
+
+.. code-block:: none
+
+ sctool task delete -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+
+task history
+============
+
+This command shows details about task run history for a given task.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task history <task type/id> --cluster <id|name>
+ [--limit <number of results>] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task history parameters
+.......................
+
+In addition to the `Global Flags`_, task history takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--limit <number of results>``
+
+Limits the number of returned results.
+
+**Default** 10
+
+=====
+
+Example: task history
+.....................
+
+.. code-block:: none
+
+ sctool task history repair/730a134a-4792-4139-bc6c-75d2ba7a1e62 -c prod-cluster
+
+ ╭──────────────────────────────────────┬────────────────────────┬────────────────────────┬──────────┬────────────────────────────────────────────────╮
+ │ ID │ Start time │ End time │ Duration │ Status │
+ ├──────────────────────────────────────┼────────────────────────┼────────────────────────┼──────────┼────────────────────────────────────────────────┤
+ │ f81ba8ad-ad79-11e8-915f-42010af000a9 │ 01 Jan 18 00:00:00 UTC │ 01 Jan 18 00:00:30 UTC │ 30s │ STOPPED │
+ │ e02d2caf-ad2a-11e8-915e-42010af000a9 │ 31 Feb 18 14:33:05 UTC │ 31 Feb 18 14:34:35 UTC │ 90s │ SUCCESS │
+ │ 7a8c6fe2-ad29-11e8-915d-42010af000a9 │ 31 Mar 18 14:23:20 UTC │ 31 Mar 18 14:23:20 UTC │ 0s │ ERROR failed to load units … │
+ │ 08f75324-610d-11e9-9aac-42010af000a9 │ 05 Apr 19 12:33:42 UTC │ 05 Apr 19 12:33:43 UTC │ 1s │ DONE │
+ │ 000681e1-610d-11e9-9aab-42010af000a9 │ 09 Apr 19 12:33:27 UTC │ 09 Apr 19 12:33:28 UTC │ 1s │ DONE │
+ │ f715fb82-610c-11e9-9aaa-42010af000a9 │ 11 Apr 19 12:33:12 UTC │ 11 Apr 19 12:33:13 UTC │ 1s │ DONE │
+ │ ee251fc0-610c-11e9-9aa9-42010af000a9 │ 13 Apr 19 12:32:57 UTC │ 13 Apr 19 12:32:58 UTC │ 1s │ DONE │
+ │ e5343b52-610c-11e9-9aa8-42010af000a9 │ 15 Apr 19 15:32:42 UTC │ 15 Apr 19 15:32:43 UTC │ 1s │ DONE │
+ │ dc435562-610c-11e9-9aa7-42010af000a9 │ 17 Apr 19 12:32:27 UTC │ 17 Apr 19 12:32:28 UTC │ 1s │ DONE │
+ ╰──────────────────────────────────────┴────────────────────────┴────────────────────────┴──────────┴────────────────────────────────────────────────╯
+
+.. _sctool-task-list:
+
+task list
+=========
+
+This command shows all of the scheduled tasks for the specified cluster.
+If the cluster is not set, this will output a table for every cluster.
+Each row contains task type and ID, separated by a slash, task properties, next activation, and last status information.
+For more information on a task, consult `task history`_ and `task progress`_.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task list [--cluster <id|name>] [--all] [--sort <sort-key>]
+ [--status <status>] [--type <task type>] [global flags]
+
+task list parameters
+....................
+
+In addition to the `Global Flags`_, task list takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--all``
+
+Lists all tasks, including those which have been disabled.
+Disabled tasks are prefixed with ``*``.
+For example ``*repair/afe9a610-e4c7-4d05-860e-5a0ddf14d7aa``.
+
+=====
+
+``--sort <sort-key>``
+
+Returns a list of tasks sorted according to the last run status and sort key which you provide.
+Accepted sort key values are:
+
+* ``start-time``
+* ``next-activation``
+* ``end-time``
+* ``status``
+
+``start-time``, ``next-activation``, and ``end-time`` are sorted in ascending order.
+
+``status`` is sorted using the following order: "NEW", "RUNNING", "STOPPED", "DONE", "ERROR", "ABORTED".
+
+=====
+
+``--status <status>``
+
+Filters tasks according to their last run status.
+Accepted values are NEW, STARTING, RUNNING, STOPPING, STOPPED, DONE, ERROR, ABORTED.
+
+=====
+
+``-t, --type <task type>``
+
+Display only tasks of a given type.
+
+=====
+
+Example: task list
+..................
+
+.. code-block:: none
+
+ sctool task list
+ Cluster: prod-cluster (c1bbabf3-cad1-4a59-ab8f-84e2a73b623f)
+ ╭───────────────────────────────────────────────────────┬──────────────────────────────────────┬───────────────────────────────┬─────────╮
+ │ Task │ Arguments │ Next run │ Status │
+ ├───────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┼─────────┤
+ │ healthcheck/ebccaade-4487-4ce9-80ee-d39e295c752e │ │ 02 Apr 20 10:47:48 UTC (+15s) │ DONE │
+ │ healthcheck_rest/eff03af0-21ee-473a-b674-5e4bedc37b8b │ │ 02 Apr 20 11:02:03 UTC (+1h) │ DONE │
+ │ backup/2d7df8bb-69bc-4782-a52f-1ec87f9c2c1c │ -L s3:manager-backup-tests-eu-west-1 │ │ RUNNING │
+ ╰───────────────────────────────────────────────────────┴──────────────────────────────────────┴───────────────────────────────┴─────────╯
+
+Setting the ``--all`` flag will also list disabled tasks which are not shown in the regular view.
+Disabled tasks are prefixed with a ``*``.
+
+task progress
+=============
+
+This command shows details of the latest run (or still running) task.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task progress <task type/id> --cluster <id|name> [--details] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task progress parameters
+........................
+
+
+In addition to the `Global flags`_, repair progress takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--details``
+
+More detailed progress data, depending on task type.
+
+====
+
+Example: task progress
+......................
+
+This example displays the progress of a running repair.
+
+.. code-block:: none
+
+ sctool task progress repair/dff91fd1-f430-4f98-8932-373644fe647e -c prod-cluster
+ Status: RUNNING
+ Start time: 17 Apr 19 12:55:57 UTC
+ Duration: 46s
+ Progress: 0.45%
+ Datacenters:
+ - dc1
+ - dc2
+ ╭───────────────────────┬───────╮
+ │ system_auth │ 3.85% │
+ │ system_distributed │ 0.00% │
+ │ system_traces │ 0.00% │
+ │ test_keyspace_dc1_rf2 │ 0.00% │
+ │ test_keyspace_dc1_rf3 │ 0.00% │
+ │ test_keyspace_dc2_rf2 │ 0.00% │
+ │ test_keyspace_dc2_rf3 │ 0.00% │
+ │ test_keyspace_rf2 │ 0.00% │
+ │ test_keyspace_rf3 │ 0.00% │
+ ╰───────────────────────┴───────╯
+
+The ``--details`` flag shows each host’s shard repair progress, with the shards numbered from zero.
+
+.. code-block:: none
+
+ sctool task progress repair/dff91fd1-f430-4f98-8932-373644fe647e -c prod-cluster --details
+ Status: RUNNING
+ Start time: 17 Apr 19 12:55:57 UTC
+ Duration: 3m0s
+ Progress: 1.91%
+ Datacenters:
+ - dc1
+ - dc2
+ ╭───────────────────────┬────────╮
+ │ system_auth │ 16.30% │
+ │ system_distributed │ 0.00% │
+ │ system_traces │ 0.00% │
+ │ test_keyspace_dc1_rf2 │ 0.00% │
+ │ test_keyspace_dc1_rf3 │ 0.00% │
+ │ test_keyspace_dc2_rf2 │ 0.00% │
+ │ test_keyspace_dc2_rf3 │ 0.00% │
+ │ test_keyspace_rf2 │ 0.00% │
+ │ test_keyspace_rf3 │ 0.00% │
+ ╰───────────────────────┴────────╯
+ ╭───────────────────────┬───────┬──────────┬───────────────┬─────────────────┬───────────────╮
+ │ system_auth │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 100.00% │ 748 │ 748 │ 0 │
+ │ 192.168.100.11 │ 1 │ 100.00% │ 757 │ 757 │ 0 │
+ │ 192.168.100.22 │ 0 │ 2.40% │ 791 │ 19 │ 0 │
+ │ 192.168.100.22 │ 1 │ 2.35% │ 807 │ 19 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 752 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 747 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ system_distributed │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 748 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 757 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 791 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ system_traces │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 748 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 757 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 740 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 922 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 930 │ 0 │ 0 │
+ │ 192.168.100.21 │ 0 │ 0.00% │ 765 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 767 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 791 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 807 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 752 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 747 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc1_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc1_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc2_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_dc2_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_rf2 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.21 │ 0 │ 0.00% │ 1349 │ 0 │ 0 │
+ │ 192.168.100.21 │ 1 │ 0.00% │ 1343 │ 0 │ 0 │
+ │ 192.168.100.22 │ 0 │ 0.00% │ 1550 │ 0 │ 0 │
+ │ 192.168.100.22 │ 1 │ 0.00% │ 1561 │ 0 │ 0 │
+ │ 192.168.100.23 │ 0 │ 0.00% │ 1450 │ 0 │ 0 │
+ │ 192.168.100.23 │ 1 │ 0.00% │ 1465 │ 0 │ 0 │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ test_keyspace_rf3 │ shard │ progress │ segment_count │ segment_success │ segment_error │
+ ├───────────────────────┼───────┼──────────┼───────────────┼─────────────────┼───────────────┤
+ │ 192.168.100.11 │ 0 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.11 │ 1 │ 0.00% │ 1339 │ 0 │ 0 │
+ │ 192.168.100.12 │ 0 │ 0.00% │ 1482 │ 0 │ 0 │
+ │ 192.168.100.12 │ 1 │ 0.00% │ 1480 │ 0 │ 0 │
+ │ 192.168.100.13 │ 0 │ 0.00% │ 1523 │ 0 │ 0 │
+ │ 192.168.100.13 │ 1 │ 0.00% │ 1528 │ 0 │ 0 │
+ ╰───────────────────────┴───────┴──────────┴───────────────┴─────────────────┴───────────────╯
+
+Example with a backup task
+
+.. code-block:: none
+
+ sctool task progress -c prod-cluster backup/f0642e3e-e1cb-44ba-8447-f8d43672bcfd
+ Arguments: -L s3:manager-backup-tests-eu-west-1
+ Status: RUNNING
+ Start time: 02 Apr 20 10:09:27 UTC
+ Duration: 40m30s
+ Progress: 1%
+ Snapshot Tag: sm_20200402100931UTC
+ Datacenters:
+ - eu-west
+ ╭──────────────┬──────────┬───────────┬──────────┬──────────────┬────────╮
+ │ Host │ Progress │ Size │ Success │ Deduplicated │ Failed │
+ ├──────────────┼──────────┼───────────┼──────────┼──────────────┼────────┤
+ │ 10.0.114.68 │ 1% │ 952.11GiB │ 13.22GiB │ 538KiB │ 0B │
+ │ 10.0.138.46 │ 1% │ 938.00GiB │ 13.43GiB │ 830MiB │ 0B │
+ │ 10.0.196.204 │ 1% │ 934.58GiB │ 13.79GiB │ 206MiB │ 0B │
+ │ 10.0.66.115 │ 1% │ 897.43GiB │ 12.17GiB │ 523KiB │ 0B │
+ ╰──────────────┴──────────┴───────────┴──────────┴──────────────┴────────╯
+
+task start
+==========
+
+This command initiates a task run.
+Note that if a repair task is already running on a cluster, other repair tasks runs on that cluster will fail.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task start <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task start parameters
+.....................
+
+In addition to the `Global Flags`_, task start takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``--continue``
+
+Try to resume the last run.
+
+**Default** true
+
+=====
+
+Example: task start
+...................
+
+This example resumes running, which was previously stopped.
+To start a repair that is scheduled but is currently not running, use the ``task update`` command making sure to set the start time to ``now``.
+See `Example: task update`_.
+
+
+If you have stopped a repair, you can resume it by running the following command.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task start -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+task stop
+=========
+
+Stops a specified task, stopping an already stopped task has no effect.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task stop <task type/id> --cluster <id|name> [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task stop parameters
+.....................
+
+In addition to the `Global flags`_, task stop takes the following parameter:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+Example: task stop
+..................
+
+This example immediately stops running repair.
+The task is not deleted and can be resumed at a later time.
+You will need the task ID for this action.
+This can be retrieved using the command ``sctool task list``.
+
+.. code-block:: none
+
+ sctool task stop -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd
+
+task update
+===========
+
+This command changes generic task parameters, such as schedule.
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool task update <task type/id> --cluster <id|name> [--enabled <bool>]
+ [--name <alias>] [--tags <list of tags>]
+ [--interval <time between task runs>]
+ [--start-date <now+duration|RFC3339>]
+ [--num-retries <times to rerun a failed task>] [global flags]
+
+.. include:: _common/task-id-note.rst
+
+task update parameters
+......................
+
+In addition to `Global flags`_, task stop takes the following parameters:
+
+=====
+
+.. include:: _common/param-cluster.rst
+
+=====
+
+``-e, --enabled``
+
+Setting enabled to false disables the task.
+The disabled task is not executed and hidden from the task list.
+To show disabled tasks invoke ``sctool task list --all`` (see `task list`_).
+
+**Default** true
+
+=====
+
+``-n, --name <alias>``
+
+Adds a name to a task.
+
+=====
+
+``--tags <list of tags>``
+
+Allows you to tag the task with a list of text.
+
+=====
+
+.. include:: _common/task-params.rst
+
+=====
+
+Example: task update
+....................
+
+This example disables the task
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/4d79ee63-7721-4105-8c6a-5b98c65c3e21 --enabled false
+
+
+This example reschedules the repair to run in 3 hours from now instead of whatever time it was supposed to run and sets the repair to run every two days.
+The new time you set replaces the time which was previously set.
+
+.. code-block:: none
+
+ sctool task update -c prod-cluster repair/143d160f-e53c-4890-a9e7-149561376cfd -s now+3h --interval 2d
+
+Show Scylla Manager version
+---------------------------
+
+This command shows the currently installed sctool version and the Scylla Manager server version.
+
+version
+=======
+
+**Syntax:**
+
+.. code-block:: none
+
+ sctool version [flags] [global flags]
+
+version parameters
+..................
+
+version takes the `Global flags`_.
+
+Example: version
+................
+
+.. code-block:: none
+
+ sctool version
+ Client version: 2.1-0.20200401.ce91f2ad
+ Server version: 2.1-0.20200401.ce91f2ad
+
diff --git a/docs/operating-scylla/manager/2.1/use-a-remote-db.rst b/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
--- a/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
+++ b/docs/operating-scylla/manager/2.1/use-a-remote-db.rst
@@ -0,0 +1,123 @@
+========================================
+Use a remote database for Scylla Manager
+========================================
+
+.. include:: /operating-scylla/manager/_common/note-versions.rst
+
+
+When you install Scylla Manager, it installs a local instance of Scylla to use as it's a database.
+You are not required to use the local instance and can use Scylla Manager with a remote database.
+
+
+**Requirements**
+
+* Scylla cluster to be used as Scylla Manager data store.
+* Package ``scylla-manager`` installed.
+
+Remove local Scylla instance
+============================
+
+The ``scylla-manager`` package is a meta package that pulls both Scylla and Scylla Manager packages.
+If you do not intend to use the local Scylla instance, you may remove it.
+
+**Procedure**
+
+1. Remove ``scylla-enterprise`` package.
+
+.. code-block:: none
+
+ sudo yum remove scylla-enterprise -y
+
+2. Remove related packages. This would also remove the Scylla Manager.
+
+.. code-block:: none
+
+ sudo yum autoremove -y
+
+3. Install the Scylla Manager client and server packages.
+
+.. code-block:: none
+
+ sudo yum install scylla-manager-client scylla-manager-server -y
+
+Edit Scylla Manager configuration
+=================================
+
+Scylla Manager configuration file ``/etc/scylla-manager/scylla-manager.yaml`` contains a database configuration section.
+
+.. code-block:: yaml
+
+ # Scylla Manager database, used to store management data.
+ database:
+ hosts:
+ - 127.0.0.1
+ # Enable or disable client/server encryption.
+ # ssl: false
+ #
+ # Database credentials.
+ # user: user
+ # password: password
+ #
+ # Local datacenter name, specify if using a remote, multi-dc cluster.
+ # local_dc:
+ #
+ # Database connection timeout.
+ # timeout: 600ms
+ #
+ # Keyspace for management data, for create statement see /etc/scylla-manager/create_keyspace.cql.tpl.
+ # keyspace: scylla_manager
+ # replication_factor: 1
+
+
+Using an editor, open the file and change relevant parameters.
+
+**Procedure**
+
+1. Edit the ``hosts`` parameter, change the IP address to the IP address or addresses of the remote cluster.
+
+2. If client/server encryption is enabled, uncomment and set the ``ssl`` parameter to ``true``.
+ Additional SSL configuration options can be set in the ``ssl`` configuration section.
+
+ .. code-block:: yaml
+
+ # Optional custom client/server encryption options.
+ #ssl:
+ # CA certificate used to validate server cert. If not set will use he host's root CA set.
+ # cert_file:
+ #
+ # Verify the hostname and server cert.
+ # validate: true
+ #
+ # Client certificate and key in PEM format. It has to be provided when
+ # client_encryption_options.require_client_auth=true is set on server.
+ # user_cert_file:
+ # user_key_file
+
+3. If authentication is needed, uncomment and edit the ``user`` and ``password`` parameters.
+
+4. If the remote cluster contains more than one node:
+
+ * If it's a single DC deployment, uncomment and edit the ``replication_factor`` parameter to match the required replication factor.
+ Note that this would use a simple replication strategy (SimpleStrategy).
+ If you want to use a different replication strategy, create ``scylla_manager`` keyspace (or another matching the ``keyspace`` parameter) yourself.
+ Refer to :doc:`Scylla Architecture - Fault Tolerance </architecture/architecture-fault-tolerance>` for more information on replication.
+
+ * If it's a multi DC deployment, create ``scylla_manager`` keyspace (or other matching the ``keyspace`` parameter) yourself.
+ Uncomment and edit the ``local_dc`` parameter to specify the local datacenter.
+
+Sample configuration of Scylla Manager working with a remote cluster with authentication and replication factor 3 could look like this.
+
+.. code-block:: yaml
+
+ database:
+ hosts:
+ - 198.100.51.11
+ - 198.100.51.12
+ user: user
+ password: password
+ replication_factor: 3
+
+Setup Scylla Manager
+====================
+
+Continue with :ref:`setup script <install-run-the-scylla-manager-setup-script>`.
diff --git a/docs/operating-scylla/manager/_common/manager-description.rst b/docs/operating-scylla/manager/_common/manager-description.rst
--- a/docs/operating-scylla/manager/_common/manager-description.rst
+++ b/docs/operating-scylla/manager/_common/manager-description.rst
@@ -0,0 +1,4 @@
+Scylla Manager is a centralized cluster administration and recurrent tasks automation tool. Scylla Manager can schedule tasks such as repairs and backups.
+Scylla Manager is available for Scylla Enterprise customers and Scylla Open Source users. With Scylla Open Source, Scylla Manager is limited to 5 nodes.
+See the Scylla Manager Proprietary Software `License Agreement <https://www.scylladb.com/scylla-manager-software-license-agreement/>`_ for details.
+Scylla Manager runs with any version of Scylla Enterprise or Open source.
\ No newline at end of file
diff --git a/docs/operating-scylla/manager/_common/manager-index.rst b/docs/operating-scylla/manager/_common/manager-index.rst
--- a/docs/operating-scylla/manager/_common/manager-index.rst
+++ b/docs/operating-scylla/manager/_common/manager-index.rst
@@ -0,0 +1,4 @@
+
+Older Scylla Manager releases:
+
+* :doc:`Scylla Manager 2.1 </operating-scylla/manager/2.1/index>`
diff --git a/docs/operating-scylla/manager/_common/note-versions.rst b/docs/operating-scylla/manager/_common/note-versions.rst
--- a/docs/operating-scylla/manager/_common/note-versions.rst
+++ b/docs/operating-scylla/manager/_common/note-versions.rst
@@ -0,0 +1,2 @@
+.. note:: You are not reading the most recent version of this documentation.
+ Go to the **latest** version of `Scylla Manager Documentation <http://scylladb.github.io/scylla-manager/>`_.
diff --git a/docs/operating-scylla/manager/index.rst b/docs/operating-scylla/manager/index.rst
--- a/docs/operating-scylla/manager/index.rst
+++ b/docs/operating-scylla/manager/index.rst
@@ -0,0 +1,27 @@
+Scylla Manager
+==============
+
+.. toctree::
+ :hidden:
+ :maxdepth: 2
+
+ Scylla Manager Docs <https://manager.docs.scylladb.com>
+ Upgrade Scylla Manager </upgrade/upgrade-manager/index>
+ Monitoring Support Matrix <https://monitoring.docs.scylladb.com/stable/reference/matrix.html>
+
+.. include:: /operating-scylla/manager/_common/manager-description.rst
+
+.. image:: scylla-...@2x.png
+ :width: 250
+ :alt: Scylla Manager Logo
+
+To get started, read the `Scylla Manager Documentation <https://manager.docs.scylladb.com/stable/index.html>`_ (Scylla Manager release 2.2 and later)
+
+Additional information:
+
+* :doc:`Upgrade Scylla Manager </upgrade/upgrade-manager/index>`
+* `Scylla Monitoring Support Matrix <https://monitoring.docs.scylladb.com/stable/reference/matrix.html>`_ - refer to this document before installing Manager if you plan to use Scylla Manager with Scylla Monitoring stack.
+* `Cluster Management, Repair and Scylla Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/>`_ on Scylla University, includes theory and some hands-on labs
+
+.. include:: /operating-scylla/manager/_common/manager-index.rst
+
diff --git a/docs/operating-scylla/manager/scylla-...@2x.png b/docs/operating-scylla/manager/scylla-...@2x.png
--- a/docs/operating-scylla/manager/scylla-...@2x.png
+++ b/docs/operating-scylla/manager/scylla-...@2x.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/1.png b/docs/operating-scylla/monitoring/2.2/1.png
--- a/docs/operating-scylla/monitoring/2.2/1.png
+++ b/docs/operating-scylla/monitoring/2.2/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/2.png b/docs/operating-scylla/monitoring/2.2/2.png
--- a/docs/operating-scylla/monitoring/2.2/2.png
+++ b/docs/operating-scylla/monitoring/2.2/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/3.png b/docs/operating-scylla/monitoring/2.2/3.png
--- a/docs/operating-scylla/monitoring/2.2/3.png
+++ b/docs/operating-scylla/monitoring/2.2/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/4.png b/docs/operating-scylla/monitoring/2.2/4.png
--- a/docs/operating-scylla/monitoring/2.2/4.png
+++ b/docs/operating-scylla/monitoring/2.2/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.2/alertmanager.png b/docs/operating-scylla/monitoring/2.2/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.2/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.2/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.2/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/grafana.png b/docs/operating-scylla/monitoring/2.2/grafana.png
--- a/docs/operating-scylla/monitoring/2.2/grafana.png
+++ b/docs/operating-scylla/monitoring/2.2/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/index.rst b/docs/operating-scylla/monitoring/2.2/index.rst
--- a/docs/operating-scylla/monitoring/2.2/index.rst
+++ b/docs/operating-scylla/monitoring/2.2/index.rst
@@ -0,0 +1,36 @@
+:orphan:
+Scylla Monitoring 2.2
+=====================
+
+.. toctree::
+ :hidden:
+ :maxdepth: 1
+
+ Scylla Monitoring Stack <monitoring-stack>
+ Scylla Monitoring Interfaces <monitoring-apis>
+ Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>
+ Troubleshoot Monitoring <monitor-troubleshoot>
+ Upgrade Monitoring </upgrade/upgrade-monitor/index>
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+
+
+.. include:: /operating-scylla/monitoring/_common/note-versions.rst
+
+.. include:: /operating-scylla/monitoring/_common/monitor-description.rst
+
+.. panel-box::
+ :title: Monitoring Scylla
+ :id: "monitoring"
+ :class: my-panel
+
+
+
+ * :doc:`Scylla Monitoring Stack <monitoring-stack>`
+ * :doc:`Scylla Monitoring Interfaces<monitoring-apis>`
+ * :doc:`Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>`
+ * :doc:`Troubleshoot Monitoring<monitor-troubleshoot>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Upgrade Guide - Monitoring </upgrade/upgrade-monitor/index>`
+ * Download the Scylla Monitoring :download:`Cheatsheet </operating-scylla/monitoring/2.2/Scylla_Monitoring_CheatSheet.pdf>`
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.2/min-prod-hw.rst
@@ -0,0 +1,24 @@
+Minimal Production System Recommendations
+-----------------------------------------
+
+* **CPU** - at least 2 physical cores/ 4vCPUs
+* **Memory** - 15GB+ DRAM
+* **Disk** - persistent disk storage is proportional to the number of cores and Prometheus retention period (see the following section)
+* **Network** - 1GbE/10GbE preferred
+
+Calculating Prometheus Minimal Disk Space requirement
+.....................................................
+
+Prometheus storage disk performance requirements: persistent block volume, for example an EC2 EBS volume
+
+Prometheus storage disk volume requirement: proportional to the number of metrics it holds. The default retention period is 15 days, and the disk requirement is around 200MB per core, assuming the default scraping interval of 15s.
+
+For example, when monitoring a 6 node Scylla cluster, each with 16 CPU cores, and using the default 15 days retention time, you will need **minimal** disk space of
+
+.. code::
+
+ 6 * 16 * 200MB ~ 20GB
+
+
+To account for unexpected events, like replacing or adding nodes, we recommend allocating at least x4-5 space, in this case, ~100GB.
+Prometheus Storage disk does not have to be as fast as Scylla disk, and EC2 EBS, for example, is fast enough and provide HA out of the box.
diff --git a/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitor-troubleshoot.rst
@@ -0,0 +1,156 @@
+Troubleshoot Monitoring
+========================
+
+
+This document describes steps that needed to be done to troubleshoot monitoring problems when using `Grafana/Prometheus`_ monitoring tool.
+
+.. _`Grafana/Prometheus`: /monitoring_apis/
+
+Problem
+~~~~~~~
+
+
+
+No Data Points
+^^^^^^^^^^^^^^
+
+``No data points`` on all data charts.
+
+Solution
+........
+If there are no data points, or if a node appears to be unreachable when you know it is, the immediate suspect is the Prometheus connectivity.
+
+Start by login to the Prometheus console:
+
+point your browser to ``http://{ip}:9090`` ({ip} is the Prometheus ip address).
+
+Go to the target tabs: ``http://{ip}:9090/targets`` and see if any of the targets is down and if there is an error message.
+
+* Not using the local network for local ip range
+
+When using Docker containers, by default, the local ip range (127.0.0.X) is inside the Docker container and not the host local address,
+if you are trying to connect to a target via the local ip range from inside a Docker container, you need to use the ``-l`` flag to enable local network stack.
+
+
+* Prometheus may be pointing to the wrong target. Check your ``prometheus/scylla_servers.yml`` and ``prometheus/node_exporter_servers.yml``. Make sure in both cases Prometheus is pulling data from the Scylla server.
+
+Or
+
+* Your dashboard and Scylla version may not be aligned. If you are running Scylla 2.0.x, you need to start the monitoring server with ``./start-all.sh``.
+
+For example:
+
+.. code-block:: shell
+
+ ./start-all.sh -v 2.0.1
+
+More on start-all.sh `options`_.
+
+.. _`options`: /monitoring_stack/
+
+
+Grafana Chart Shows Error (!) Sign
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run this procedure on the Monitoring server.
+
+All of Grafana chart shows error (!) sign.
+There is a problem with the connection between Grafana and Prometheus. On the monitoring server:
+
+Solution
+.........
+
+1. Check Prometheus is running using ``sudo docker ps``.
+If it is not running check the ``prometheus.yml`` for errors.
+
+For example:
+
+.. code-block:: shell
+
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 41bd3db26240 monitor "/docker-entrypoin..." 25 seconds ago Up 23 seconds 7000-7001/tcp, 9042/tcp, 9160/tcp, 9180/tcp, 10000/tcp monitor
+
+2. If it is running, go to "Data Source" in the Grafana GUI, choose Prometheus and click Test Connection.
+
+Grafana Shows Server Level Metrics, but not Scylla Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana shows server level metrics like disk usage, but not Scylla metrics.
+Prometheus fails to fetch metrics from Scylla servers.
+
+Solution
+.........
+
+* use ``curl <scylla_node>:9180/metrics`` to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+For example
+
+.. code-block:: shell
+
+ curl 172.17.0.2:9180/metrics
+
+Grafana Shows Scylla Metrics, but not Server Level Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana dashboard shows Scylla metrics, such as load, but not server metrics like disk usage.
+Prometheus fail to fetch metrics from ``node_exporter``.
+
+Solution
+.........
+
+1. Make sure ``node_exporter`` is running on each Scylla server. ``node_exporter`` is installed by ``scylla_setup``.
+If it does not, make sure to install and run it.
+
+2. If it is running, use ``curl <scylla_node>:9100/metrics`` (where 172.17.0.2 is a Scylla server IP) to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+Notice to users upgrading to Scylla Open Source 3.0 or Scylla Enterprise 2019.1
+................................................................................
+
+While upgrading you need to upgrade the ``node_exporter`` from 0.14 to 0.17 version.
+
+If the node_exporter service is not starting it may be that it needs to be updated manually.
+
+Check the node_exporter version ``node_exporter --version`` if it shows 0.14 check the node_exporter section
+in the `upgrade guide`_.
+
+.. _`upgrade guide`: /upgrade/upgrade-opensource/upgrade-guide-from-2.3-to-3.0/
+
+
+
+Working with wire-shark
+^^^^^^^^^^^^^^^^^^^^^^^
+
+No metrics shown in Scylla monitor.
+
+1. Install `wire-shark`_
+
+.. _`wire-shark`: https://www.wireshark.org/#download
+
+2. Capture the traffic between Scylla monitor and Scylla node using the ``tshark`` command.
+``tshark -i <network interface name> -f "dst port 9180"``
+
+For example:
+
+.. code-block:: shell
+
+ tshark -i eth0 -f "dst port 9180"
+
+Capture from Scylla node towards Scylla monitor server.
+
+Scylla is running.
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 66 59212 > 9180 [ACK] Seq=317 Ack=78193 Win=158080 Len=0 TSval=79869679 TSecr=3347447210
+
+Scylla is not running
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 74 60440 > 9180 [SYN] Seq=0 Win=29200 Len=0 MSS=1460 SACK_PERM=1 TSval=79988291 TSecr=0 WS=128
+
+
+
+.. include:: /troubleshooting/_common/ts-return.rst
diff --git a/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitor-without-docker.2.1.rst
@@ -0,0 +1,370 @@
+Deploying Scylla Monitoring Without Docker
+==================================================================
+
+The following instructions will help to deploy :doc:`Scylla Monitoring Stack</operating-scylla/monitoring/2.2/monitoring-stack/>` in the case you can not use the docker version.
+
+Please note, Scylla recommends you use the docker version as it will provide you with most updated, current scylla monitoring system.
+
+.. include:: /operating-scylla/monitoring/2.2/min-prod-hw.rst
+
+The main item to set an alert on is the available disk space in the monitoring system. Data is indefinitely accrued on the Prometheus data directory. The current monitoring solution does not churn data.
+
+Install Scylla Monitor
+----------------------
+
+The following procedure is using a ``CentOS 7`` based instance
+
+1. Download the latest monitoring release.
+
+``wget https://github.com/scylladb/scylla-monitoring/archive/scylla-monitoring-2.2.tar.gz``
+
+
+2. open the tar
+
+``tar -xvf scylla-monitoring-2.2.tar.gz``
+
+Install Alertmanager
+--------------------
+
+Tested with alertmanager 0.16.0 version
+
+1. Install `alertmanager`_
+
+.. _`alertmanager` : https://prometheus.io/download/
+
+2. Copy the following file: ``rule_config.yml`` from ``scylla-monitoring-scylla-monitoring-2.2/prometheus`` directory to ``alertmanager.yml`` in the alertmanager installation directory.
+
+For example:
+
+.. code-block:: shell
+
+ cp -p /home/centos/scylla-monitoring-scylla-monitoring-2.2/prometheus/rule_config.yml /home/centos/alertmanager-0.16.0.linux-amd64/alertmanager.yml
+
+3. Start the Alertmanager
+
+For example:
+
+.. code-block:: shell
+
+ ./alertmanager
+
+
+4. Verify that Alertmanager is up and running, point your browser to the Alertmanager IP:Port
+
+For example:
+
+.. code-block:: shell
+
+ http://192.168.135.166:9093/
+
+.. image:: alertmanager.png
+
+
+Install Prometheus
+------------------
+
+Tested with prometheus 2.6.1 version
+
+1. Install `Prometheus`_
+
+.. _`Prometheus` : https://prometheus.io/download/
+
+2. Copy the following files: ``scylla_servers.yml``, ``node_exporter_servers.yml``, ``prometheus.rules.yml`` from ``scylla-monitoring-scylla-monitoring-2.2/prometheus`` directory to prometheus installation directory.
+
+Copy ``prometheus/prometheus.yml.template`` to ``prometheus.yml``
+
+For example:
+
+.. code-block:: shell
+
+ cp -p /home/centos/scylla-monitoring-scylla-monitoring-2.2/prometheus/*.yml /home/centos/prometheus-2.6.1.linux-amd64
+
+3. Edit the ``prometheus.yml`` file to point to the correct static data sources.
+
+.. note:: Make sure to include the ``honor_labels: false`` parameter in the prometheus.yml file.
+
+.. code-block:: shell
+
+ sudo vi /<prometheus_installation_location>/prometheus-2.6.1.linux-amd64/prometheus.yml
+
+Set the alertmanger address and port by replacing ``AM_ADDRESS`` in the file.
+
+For example if the alertmanager will run on the same host:
+
+.. code-block:: shell
+
+ alerting:
+ alertmanagers:
+ - static_configs:
+ - targets:
+ - 127.0.0.1:9093
+
+For example the scrap config for scylla:
+
+.. code-block:: shell
+
+ global:
+ scrape_interval: 5s # By default, scrape targets every 5 second.
+ scrape_timeout: 4s # Timeout before trying to scape a target again
+
+ # Attach these labels to any time series or alerts when communicating with
+ # external systems (federation, remote storage, Alertmanager).
+ external_labels:
+ monitor: 'scylla-monitor'
+
+ scrape_configs:
+ - job_name: scylla
+ honor_labels: false
+ file_sd_configs:
+ - files:
+ - /home/centos/prometheus-2.6.1.linux-amd64/scylla_servers.yml
+ relabel_configs:
+ - source_labels: [__address__]
+ regex: '(.*):.+'
+ target_label: instance
+ replacement: '${1}'
+
+
+4. Edit the, ``scylla_servers.yml``, ``node_exporter_servers.yml`` and ``scylla_manager_serer.yml`` files to point to your Scylla nodes.
+
+.. note::
+ With Scylla Monitoring version 2.2, you no longer need to configure ``node_exporter_server``. Instead, in the prometheus scrap config of the node_exporter
+ you can use the same file you used for scylla and Prometheus will assume you have a node_exporter running on each Scylla server.
+
+Add the labels for the cluster and data-center
+
+``scylla_servers.yml``:
+
+For example:
+
+.. code-block:: shell
+
+ cat scylla_servers.yml
+ # List Scylla end points
+
+ - targets:
+ - 192.168.66.6:9180
+ - 192.168.66.244:9180
+ labels:
+ cluster: cluster1
+ dc: dc1
+ - targets:
+ - 172.17.0.3:9180
+ labels:
+ cluster: cluster1
+ dc: dc2
+
+.. note::
+ See the previous note about deprecating the ``node_exporter_servers.yml`` file.
+
+``node_exporter_servers.yml``:
+
+For example:
+
+.. code-block:: shell
+
+ cat node_exporter_servers.yml
+ # List end points with node exporter
+
+ - targets:
+ - '192.168.66.6:9100'
+ - '192.168.66.244:9100'
+ labels:
+ cluster: cluster1
+ dc: dc1
+ - targets:
+ - 172.17.0.3:9100
+ labels:
+ cluster: cluster1
+ dc: dc2
+
+``scylla_manager_serer.yml``
+
+For example:
+
+.. code-block:: shell
+
+ - targets:
+ - 127.0.0.1:56090
+
+5. Create a data directory for prometheus to store the metrics data
+
+For example:
+
+.. code-block:: shell
+
+ sudo mkdir /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+
+6. Start Prometheus server:
+
+For example:
+
+.. code-block:: shell
+
+ sudo ./prometheus --config.file=prometheus.yml --storage.tsdb.path /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+Data should start accumulate on: /home/centos/prometheus-2.6.1.linux-amd64/mydata
+
+7. Verify that Prometheus is up and running, point your browser to the Prometheus IP:Port
+
+For example:
+
+.. code-block:: shell
+
+ http://192.168.135.166:9090/
+
+.. image:: 1.png
+
+Prometheus console should be visible
+
+8. Verify that the node_exporter and scylla metrics accumulating in the server by executing a query through the console
+
+For example:
+
+``node_memory_MemFree``
+
+.. image:: 2.png
+
+And
+
+``scylla_reactor_utilization``
+
+.. image:: 3.png
+
+At this point Scylla is emitting the metrics and Prometheus is able to store them.
+
+
+Install Grafana
+---------------
+
+1. Install Grafana base on the instructions `here`_ make sure to use version 5.0.0 or higher
+
+.. _`here` : http://docs.grafana.org/installation/
+
+Depends if you installed Grafana from a repository (yum install), or if you downloaded the zip version, the directory structure will be
+different in the rest of the steps.
+
+2. Access Scylla-Grafana-monitoring directory
+
+``cd /home/centos/scylla-monitoring-scylla-monitoring-2.2/``
+
+3. Copy the plugins to the grafana plugins directory (by default ``/var/lib/grafana/``)
+
+.. code-block:: shell
+
+ sudo cp -r grafana/plugins /var/lib/grafana/
+
+If you installed Grafana from packages, instead of ``/var/lib/grafana/`` you should copy it to ``public/app`` inside the directory you
+opened Grafana in.
+
+For example:
+
+.. code-block:: shell
+
+ cp -r grafana/plugins /home/centos/grafana-5.4.3/public/app
+
+4. Generate the dashboards you would like to load and provision them
+
+For example Scylla version 3.0 and Scylla Manager version 1.3
+
+.. code-block:: shell
+
+ ./generate-dashboards.sh -v 3.0 -M 1.3
+
+For Grafana installed with ``yum install``
+
+.. code-block:: shell
+
+ sudo cp grafana/provisioning/dashboards/load.* /etc/grafana/provisioning/dashboards/
+ sudo mkdir -p /var/lib/grafana/dashboards
+ sudo cp -r grafana/build/* /var/lib/grafana/dashboards
+
+For Grafana installed from packages
+
+.. code-block:: shell
+
+ cp -p -r grafana/build/* /home/centos/grafana-5.4.3/public/build/
+ cp -p grafana/provisioning/dashboards/load.* /home/centos/grafana-5.4.3/conf/provisioning/dashboards/
+
+Edit the ``load.*`` files in ``/home/centos/grafana-5.4.3/conf/provisioning/dashboards/`` for the correct path,
+for example ``load.3.0.yaml`` would point to: ``/home/centos/grafana-5.4.3/public/build/ver_3.0``
+
+
+5. Set the data source by copy ``datasource.yml`` and edit it
+
+.. code-block:: shell
+
+ sudo cp grafana/datasource.yml /etc/grafana/provisioning/datasources/
+
+For Grafana installed from packages
+
+.. code-block:: shell
+
+ cp -p grafana/datasource.yml /home/centos/grafana-5.4.3/conf/provisioning/datasources/
+
+You should set the prometheus and the alertmanager ip and port.
+
+For example
+
+.. code-block:: shell
+
+ sudo cat /etc/grafana/provisioning/datasources/datasource.yml
+ apiVersion: 1
+ datasources:
+ - name: prometheus
+ type: prometheus
+ url: http://192.168.135.167:9090
+ access: proxy
+ basicAuth: false
+
+ - name: alertmanager
+ type: camptocamp-prometheus-alertmanager-datasource
+ orgId: 1
+ typeLogoUrl: public/img/icn-datasource.svg
+ access: proxy
+ url: http://192.168.135.166:9093
+ password:
+ user:
+ database:
+ basicAuth:
+ isDefault:
+ jsonData:
+ severity_critical: '4'
+ severity_high: '3'
+ severity_warning: '2'
+ severity_info: '1'
+
+6. Start the Grafana service
+
+For Grafana installed with `yum install`
+
+``sudo service grafana-server start``
+
+For Grafana installed from packages:
+
+``cp -p /home/centos/grafana-5.4.3/conf/sample.ini /home/centos/grafana-5.4.3/conf/scylla.ini``
+
+Edit scylla.ini to reflect the right paths in the paths section of the file.
+
+
+.. code-block:: shell
+
+ plugins = /home/centos/grafana-5.4.3/public/app/plugins
+ provisioning = /home/centos/grafana-5.4.3/conf/provisioning
+
+
+Start the server:
+
+.. code-block:: shell
+
+ cd /home/centos/grafana-5.4.3/
+ ./bin/grafana-server -config /home/centos/grafana-5.4.3/conf/scylla.ini
+
+7. Make sure Grafana is running
+
+Point your browser to the Grafana server port 3000, the assumption is that Grafana and Prometheus are collocated on the same server.
+
+.. image:: grafana.png
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/monitor.png b/docs/operating-scylla/monitoring/2.2/monitor.png
--- a/docs/operating-scylla/monitoring/2.2/monitor.png
+++ b/docs/operating-scylla/monitoring/2.2/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitoring-apis.rst
@@ -0,0 +1,47 @@
+
+Monitoring Interfaces
+=====================
+
+Scylla exposes two interfaces for online monitoring, as described below
+
+Prometheus
+----------
+By default, Scylla listen on port 9180 for `Prometheus <https://prometheus.io/>`_ requests. To connect a Prometheus server to scylla in your prometheus.yaml configuration file, add scylla as a target with :code:`your-ip:9180`
+
+For more information on monitoring Scylla with Prometheus see :doc:`Scylla Monitoring Stack <monitoring-stack/>`
+
+You can change Prometheus listening address and port in scylla.yaml file
+
+.. code-block:: yaml
+
+ # prometheus port
+ # By default, Scylla opens prometheus API port on port 9180
+ # setting the port to 0 will disable the prometheus API.
+ prometheus_port: 9180
+ #
+ # prometheus address
+ # By default, Scylla binds all interfaces to the prometheus API
+ # It is possible to restrict the listening address to a specific one
+ prometheus_address: 0.0.0.0
+
+Collectd
+--------
+
+Starting from Scylla version 2.3 `scyllatop <http://www.scylladb.com/2016/03/22/scyllatop/>`_ will not use Collectd any more.
+
+By default, Scylla send metrics to a local `Collectd <https://collectd.org/>`_ process, allowing you to watch Scylla status with `scyllatop <http://www.scylladb.com/2016/03/22/scyllatop/>`_. Scylla can also sends metric over Collectd protocol to external Collectd server, `Graphite <http://graphite.wikidot.com/>`_ or similar tools. To forward metrics to external server, update :code:`/etc/collectd.d/scylla.conf` to work as a proxy:
+
+.. code-block:: apacheconf
+
+ LoadPlugin network
+ <Plugin "network">
+ Listen "127.0.0.1" "25826"
+ Server "remote-ip" "25826"
+ Forward true
+ </Plugin>
+
+Where :code:`remote-ip` is the IP of your external Collectd server. Make sure to keep other elements of the file as is. Restart the collectd server for the new configuration to apply :code:`sudo service collectd restart`
+
+To change sample rate of Scylla metrics, update the :code:`SCYLLA_ARGS` line in :code:`/etc/sysconfig/scylla-server` file, parameter :code:`--collectd-poll-period 3000` (number in ms)
+
+
diff --git a/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.2/monitoring-stack.rst
@@ -0,0 +1,168 @@
+Scylla Monitoring Stack
+=======================
+
+This document describes the setup of Scylla monitoring Stack, base on :doc:`Scylla Prometheus API <monitoring-apis>`.
+
+Scylla monitoring stack consists of three components, wrapped in Docker containers:
+
+* `prometheus` - collects and stores metrics
+* `alertmanager` - handles alerts
+* `grafana` - dashboard server
+
+.. image:: monitor.png
+
+The monitoring stack needs to be installed on a dedicated server, external to the Scylla cluster. Make sure the monitoring server have access to the Scylla nodes so that it can pull the metrics over the Prometheus API.
+
+For evaluation, you can run Scylla monitoring stack on any server (or laptop) that can handle two Docker instances at the same time. For production, see recommendation below.
+
+.. include:: min-prod-hw.rst
+
+
+Prerequisites
+.............
+
+* `docker`_
+
+.. _`docker`: https://www.docker.com/
+
+
+Procedure
+.........
+
+1. Download and extract the latest `Scylla Monitoring Stack binary`_; for example, for release 2.2.0
+
+.. _`Scylla Monitoring Stack binary`: https://github.com/scylladb/scylla-monitoring/releases
+
+.. code-block:: sh
+
+ wget https://github.com/scylladb/scylla-monitoring/archive/scylla-monitoring-2.2.tar.gz
+ tar -xvf scylla-monitoring-2.2.tar.gz
+ cd scylla-monitoring-scylla-monitoring-2.2
+
+As an alternative, you can clone and use the git repository directly.
+
+.. code-block:: sh
+
+ git clone https://github.com/scylladb/scylla-monitoring.git
+ cd scylla-monitoring
+ git checkout branch-2.2
+
+2. Start docker service if needed
+
+.. code-block:: sh
+
+ centos $ sudo service docker start
+ ubuntu $ sudo systemctl restart docker
+
+
+
+3. Update ``prometheus/scylla_servers.yml`` with the targets' IPs (the servers you wish to monitor).
+
+.. note::
+ It is important that the dc in the target files will match the datacenters names used by Scylla.
+ Use the ``nodetool status`` command to validate the datacenter names used by Scylla.
+
+For example:
+
+.. code-block:: yaml
+
+ targets:
+ - 172.17.0.2
+ - 172.17.0.3
+ labels:
+ cluster: cluster1
+ dc: dc1
+
+
+For general node information (disk, network, etc.) Scylla Monitoring Stack uses the node_exporter agent that runs on the same machine as Scylla does.
+By default, Prometheus will assume you have a node_exporter running on each machine. If this is not the case, you can override the node_exporter
+targets configuration file by creating an additional
+file and pass it with the ``-n`` flag.
+
+.. note::
+ By default, there is no need to configure ``node_exporter_server.yml``. Prometheus will use the same targets it uses for
+ Sylla and will assume you have a node_exporter
+ running on each Scylla server.
+
+
+It is possible to configure your own target file instead of updating ``scylla_servers.yml``, using the ``-s`` for scylla target file.
+
+For example:
+
+.. code-block:: yaml
+
+ ./start-all.sh -s my_scylla_server.yml -d data_dir
+
+
+Use Labels to mark different Data Centers
+
+As can be seen in the examples, each target has its own set of labels to mark the cluster name and the data center (dc).
+You can add multiple targets in the same file for multiple clusters or multiple data centers.
+
+4. Connect to `Scylla Manager`_ by updating ``prometheus/scylla_manager_servers.yml``
+If you are using Scylla Manager, you should set its ip.
+
+.. _`Scylla Manager`: /operating-scylla/manager/
+
+For example
+
+.. code-block:: yaml
+
+ # List Scylla Manager end points
+
+ - targets:
+ - 127.0.0.1:56090
+
+
+Note that you do not need to add labels to the Scylla Manager targets.
+
+
+Start and Stop
+..............
+
+Start
+
+.. code-block:: yaml
+
+ ./start-all.sh -d data_dir
+
+
+Stop
+
+.. code-block:: yaml
+
+ ./kill-all.sh
+
+Setting Specific Version
+........................
+
+By default, start-all.sh will start with dashboards for the latest two Scylla versions and the latest Scylla Manager version.
+
+You can specify specific scylla version with the ``-v`` flag and Scylla Manager version with ``-M`` flag
+
+For example:
+
+.. code-block:: sh
+
+ ./start-all.sh -v 3.0,master -M 1.3
+
+will load the dashboards for Scylla versions ``3.0`` and ``master`` and the dashboard for Scylla Manager ``1.3``
+
+View Grafana Monitor
+....................
+
+Point your browser to ``your-server-ip:3000``
+By default, Grafana authentication is disabled. To enable it and set a password for user admin use the ``-a`` option
+
+For example:
+
+.. code-block:: yaml
+
+ 10.10.0.1:3000
+
+* Choose Disk and network interface
+
+The dashboard holds a drop down menu at its upper left corner for disk and network interface.
+You should choose relevant disk and interface for the dashboard to show the graphs.
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/1.png b/docs/operating-scylla/monitoring/2.3/1.png
--- a/docs/operating-scylla/monitoring/2.3/1.png
+++ b/docs/operating-scylla/monitoring/2.3/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/2.png b/docs/operating-scylla/monitoring/2.3/2.png
--- a/docs/operating-scylla/monitoring/2.3/2.png
+++ b/docs/operating-scylla/monitoring/2.3/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/3.png b/docs/operating-scylla/monitoring/2.3/3.png
--- a/docs/operating-scylla/monitoring/2.3/3.png
+++ b/docs/operating-scylla/monitoring/2.3/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/4.png b/docs/operating-scylla/monitoring/2.3/4.png
--- a/docs/operating-scylla/monitoring/2.3/4.png
+++ b/docs/operating-scylla/monitoring/2.3/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.3/alertmanager.png b/docs/operating-scylla/monitoring/2.3/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.3/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.3/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/cql-optimization.rst b/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/2.3/cql-optimization.rst
@@ -0,0 +1,138 @@
+The CQL Optimization Dashboard
+==============================
+
+The CQL Optimization Dashboard (introduce in Scylla monitoring 2.2) is a tool to help identify potentials issues with queries, data model and driver.
+
+.. figure:: cql_optimization_master.png
+
+ **The CQL Optimization Dashboard**
+
+The dashboard holds gauges and graphs. When inspecting the system, we like the gauge to be near zero and the graphs as low as possible.
+
+.. note:: Besides your queries, there are queries generated by the cql driver and internal queries to the system tables which can be misleading when testing with low traffic.
+
+The following sections describe each of the dashboard's panel
+
+Prepared Statements
+^^^^^^^^^^^^^^^^^^^
+
+:ref:`Prepared statements <prepared-statements>` are queries that are first defined as a template with place holders for the values and then that template is used
+multiple times with different values.
+
+Using prepared statements has the following benefits:
+
+* The database only needs to parse the query once
+* The driver can route the query to the right node
+* Using place-holders and values is safer and prevents CQL-Injection
+
+The **CQL Non-Prepared Queries** Gauge shows the percentage of queries that are not prepared.
+
+The **CQL Non-Prepared Queries** Graph shows the rate of the queries. Make sure both are low.
+
+Token Aware
+^^^^^^^^^^^
+
+Scylla is a distributed database, with each node contains only part of the data - a range of the token ring.
+Ideally, a query would reach the node that holds the data (one of the replicas), failing to do so would mean the coordinator
+will need to send the query internally to a replica, result with a higher latency,
+and more resources usage.
+
+Typically, your driver would know how to route the queries to a replication node, but using non-prepared statements, non-token-aware driver
+or load-balance can cause the query to reach a node that is not a replica.
+
+The **Non-Token Aware** Gauge shows the percentage of queries that reached a node that does not hold that data (a node that is not a replica-node).
+
+The **Non-Token Aware Queries** Graph shows the rate of the queries that did not reach a replica-node, make sure both are low.
+
+Paged Queries
+^^^^^^^^^^^^^
+
+By default, read queries are paged, this means that Scylla will break the results into multiple chunks limiting the reply size.
+Non-Paged queries require all results be returned in one result increasing the overall load of the system and clients and should be avoided.
+
+The **Non-Paged CQL Reads** Gauge shows the percentage of non-paged read queries that did not use paging.
+
+The **Non-Paged CQL Reads** Graph shows the rate of the non-paged queries, make sure both are low.
+
+
+Reversed CQL Reads
+^^^^^^^^^^^^^^^^^^
+
+Scylla supports compound primary keys with a clustering column, this kind of primary keys allows an efficient way
+to return sorted results that are sorted by the clustering column.
+
+Querying with an order different than the order the ``CLUSTERING ORDER BY`` was defined is inefficient and should be avoided.
+
+For example, look at the following table:
+
+.. code-block:: shell
+
+ CREATE TABLE ks1.table_demo (
+ category text,
+ type int,
+ PRIMARY KEY (category, type))
+ WITH CLUSTERING ORDER BY (type DESC);
+
+
+The following query uses reverse order:
+
+.. code-block:: shell
+
+ select * from ks1.table_demo where category='cat1' order by type ASC;
+
+The **Reversed CQL Reads** Gauge shows the percentage of read queries that use ``ORDER BY`` that is different than the ``CLUSTERING ORDER BY``.
+
+The **Reversed CQL Reads** Graph shows the rate of the read queries that use ``ORDER BY`` that is different than the ``CLUSTERING ORDER BY``, make sure both are low.
+
+ALLOW FILTERING
+^^^^^^^^^^^^^^^
+
+Scylla supports server side data filtering that is not based on the primary key. This means Scylla would read data and then filter and
+return part of it to the user. Data that is read and then filtered is an overhead to the system.
+
+These kinds of queries can create a big load on the system, and should be used with care.
+
+The CQL optimization dashboard, check for two things related to queries that use ``ALLOW FILTERING`` how many such queries exist and how much of the data that was read was
+dropped before returning to the client.
+
+The **ALLOW FILTERING CQL Reads** Gauge shows the percentage of read queries that use ``ALLOW FILTERING``.
+
+The **ALLOW FILTERING CQL Reads** Graph shows the rate of the read queries that use ``ALLOW FILTERING``, make sure both are low.
+
+The **ALLOW FILTERING Filtered Rows** Gauge shows the percentage of rows that were read and then filtered, this is an indication of the additional overhead to the system.
+
+The **ALLOW FILTERING Filtered Rows** Graph shows multiple graphs: the rows that were read, the rows that matched and the rows that were dropped. Rows that
+were dropped are an additional overhead to the system.
+
+Cross DC read requests
+^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+ The CQL Optimization Dashboard relies on the definition of nodes per Data Center in the Monitoring Stack (prometheus/scylla_servers.yml) to match the Data Center names used in Scylla Cluster.
+ If this is not the case, you will see the wrong result.
+
+In a typical situation, a client performs a read from the nearest data-center and that query is performed local to the data-center.
+A read request that ends up causing traffic between data-centers adds additional overhead to the system.
+
+The **Cross DC read requests** Gauge shows the percentage of read queries that caused a request to an external data-center, make sure it is low or zero.
+
+
+Available from Scylla Monitoring Version 2.3
+********************************************
+Cross shard
+^^^^^^^^^^^
+Scylla uses a shared-nothing model that shards all requests onto individual cores. Scylla runs one application thread-per-core, and depends on explicit message passing, not shared memory between threads.
+This design avoids slow, unscalable lock primitives and cache bounces.
+
+Ideally, each request to a Scylla node reaches the right core (shard), avoiding internal communication between cores.
+This is not always the case, for example, when using a non-shard-aware Scylla driver (see more here_)
+
+.. _here: /using-scylla/drivers/index/
+
+New panels in the CQL Optimization dashboard were added to help identify cross-shard traffic.
+
+The **Cross Shard** Gauge shows the percentage of queries that reach a shard that does not hold the data.
+
+The **Cross Shard Queries** Graph shows the rate of the queries that did not reach a shard with the data, make sure both are low.
+
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.3/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/grafana.png b/docs/operating-scylla/monitoring/2.3/grafana.png
--- a/docs/operating-scylla/monitoring/2.3/grafana.png
+++ b/docs/operating-scylla/monitoring/2.3/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/index.rst b/docs/operating-scylla/monitoring/2.3/index.rst
--- a/docs/operating-scylla/monitoring/2.3/index.rst
+++ b/docs/operating-scylla/monitoring/2.3/index.rst
@@ -0,0 +1,35 @@
+:orphan:
+Scylla Monitoring 2.3
+=====================
+
+.. toctree::
+ :hidden:
+
+ Scylla Monitoring Stack <monitoring-stack>
+ Scylla Monitoring Interfaces <monitoring-apis>
+ Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>
+ Troubleshoot Monitoring <monitor-troubleshoot>
+ Troubleshoot Integration with Scylla Manager </troubleshooting/manager-monitoring-integration/>
+ Upgrade Monitoring </upgrade/upgrade-monitor/index>
+ CQL Optimization Dashboard <cql-optimization>
+ Adding and Modifying Dashboards <updating-dashboard>
+
+.. include:: /operating-scylla/monitoring/_common/note-versions.rst
+
+.. include:: /operating-scylla/monitoring/_common/monitor-description.rst
+
+.. panel-box::
+ :title: Monitoring Scylla
+ :id: "monitoring"
+ :class: my-panel
+
+ * :doc:`Scylla Monitoring Stack <monitoring-stack>`
+ * :doc:`Scylla Monitoring Interfaces<monitoring-apis>`
+ * :doc:`Deploy Scylla Monitoring Without Docker <monitor-without-docker.2.1>`
+ * :doc:`Troubleshoot Monitoring<monitor-troubleshoot>`
+ * :doc:`Troubleshooting guide for Scylla Manager and Scylla Monitoring integration </troubleshooting/manager-monitoring-integration/>`
+ * :doc:`Upgrade Guide - Monitoring </upgrade/upgrade-monitor/index>`
+ * Download the Scylla Monitoring :download:`Cheatsheet </operating-scylla/monitoring/2.3/Scylla_Monitoring_CheatSheet.pdf>`
+ * :doc:`CQL Optimization Dashboard <cql-optimization>`
+ * :doc:`Adding and Modifying Dashboards <updating-dashboard>`
+
diff --git a/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.3/min-prod-hw.rst
@@ -0,0 +1,24 @@
+Minimal Production System Recommendations
+-----------------------------------------
+
+* **CPU** - at least 2 physical cores/ 4vCPUs
+* **Memory** - 15GB+ DRAM
+* **Disk** - persistent disk storage is proportional to the number of cores and Prometheus retention period (see the following section)
+* **Network** - 1GbE/10GbE preferred
+
+Calculating Prometheus Minimal Disk Space requirement
+.....................................................
+
+Prometheus storage disk performance requirements: persistent block volume, for example an EC2 EBS volume
+
+Prometheus storage disk volume requirement: proportional to the number of metrics it holds. The default retention period is 15 days, and the disk requirement is around 200MB per core, assuming the default scraping interval of 15s.
+
+For example, when monitoring a 6 node Scylla cluster, each with 16 CPU cores, and using the default 15 days retention time, you will need **minimal** disk space of
+
+.. code::
+
+ 6 * 16 * 200MB ~ 20GB
+
+
+To account for unexpected events, like replacing or adding nodes, we recommend allocating at least x4-5 space, in this case, ~100GB.
+Prometheus Storage disk does not have to be as fast as Scylla disk, and EC2 EBS, for example, is fast enough and provide HA out of the box.
diff --git a/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitor-troubleshoot.rst
@@ -0,0 +1,154 @@
+Troubleshoot Monitoring
+========================
+
+
+This document describes steps that needed to be done to troubleshoot monitoring problems when using `Grafana/Prometheus`_ monitoring tool.
+
+.. _`Grafana/Prometheus`: /monitoring_apis/
+
+Problem
+~~~~~~~
+
+
+
+No Data Points
+^^^^^^^^^^^^^^
+
+``No data points`` on all data charts.
+
+Solution
+........
+If there are no data points, or if a node appears to be unreachable when you know it is, the immediate suspect is the Prometheus connectivity.
+
+Start by login to the Prometheus console:
+
+point your browser to ``http://{ip}:9090`` ({ip} is the Prometheus ip address).
+
+Go to the target tabs: ``http://{ip}:9090/targets`` and see if any of the targets is down and if there is an error message.
+
+* Not using the local network for local ip range
+
+When using Docker containers, by default, the local ip range (127.0.0.X) is inside the Docker container and not the host local address,
+if you are trying to connect to a target via the local ip range from inside a Docker container, you need to use the ``-l`` flag to enable local network stack.
+
+
+* Prometheus may be pointing to the wrong target. Check your ``prometheus/scylla_servers.yml`` and ``prometheus/node_exporter_servers.yml``. Make sure in both cases Prometheus is pulling data from the Scylla server.
+
+Or
+
+* Your dashboard and Scylla version may not be aligned. If you are running Scylla 2.0.x, you need to start the monitoring server with ``./start-all.sh``.
+
+For example:
+
+.. code-block:: shell
+
+ ./start-all.sh -v 2.0.1
+
+More on start-all.sh `options`_.
+
+.. _`options`: /monitoring_stack/
+
+
+Grafana Chart Shows Error (!) Sign
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run this procedure on the Monitoring server.
+
+All of Grafana chart shows error (!) sign.
+There is a problem with the connection between Grafana and Prometheus. On the monitoring server:
+
+Solution
+.........
+
+1. Check Prometheus is running using ``sudo docker ps``.
+If it is not running check the ``prometheus.yml`` for errors.
+
+For example:
+
+.. code-block:: shell
+
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 41bd3db26240 monitor "/docker-entrypoin..." 25 seconds ago Up 23 seconds 7000-7001/tcp, 9042/tcp, 9160/tcp, 9180/tcp, 10000/tcp monitor
+
+2. If it is running, go to "Data Source" in the Grafana GUI, choose Prometheus and click Test Connection.
+
+Grafana Shows Server Level Metrics, but not Scylla Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana shows server level metrics like disk usage, but not Scylla metrics.
+Prometheus fails to fetch metrics from Scylla servers.
+
+Solution
+.........
+
+* use ``curl <scylla_node>:9180/metrics`` to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+For example
+
+.. code-block:: shell
+
+ curl 172.17.0.2:9180/metrics
+
+Grafana Shows Scylla Metrics, but not Server Level Metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grafana dashboard shows Scylla metrics, such as load, but not server metrics like disk usage.
+Prometheus fail to fetch metrics from ``node_exporter``.
+
+Solution
+.........
+
+1. Make sure ``node_exporter`` is running on each Scylla server. ``node_exporter`` is installed by ``scylla_setup``.
+If it does not, make sure to install and run it.
+
+2. If it is running, use ``curl <scylla_node>:9100/metrics`` (where 172.17.0.2 is a Scylla server IP) to fetch binary metric data from Scylla. If curl does not return data, the problem is the connectivity between the monitoring and Scylla server. Please check your IPs and firewalls.
+
+Notice to users upgrading to Scylla Open Source 3.0 or Scylla Enterprise 2019.1
+................................................................................
+
+While upgrading you need to upgrade the ``node_exporter`` from 0.14 to 0.17 version.
+
+If the node_exporter service is not starting it may be that it needs to be updated manually.
+
+Check the node_exporter version ``node_exporter --version`` if it shows 0.14 check the node_exporter section
+in the `upgrade guide`_.
+
+.. _`upgrade guide`: /upgrade/upgrade-opensource/upgrade-guide-from-2.3-to-3.0/
+
+
+
+Working with wire-shark
+^^^^^^^^^^^^^^^^^^^^^^^
+
+No metrics shown in Scylla monitor.
+
+1. Install `wire-shark`_
+
+.. _`wire-shark`: https://www.wireshark.org/#download
+
+2. Capture the traffic between Scylla monitor and Scylla node using the ``tshark`` command.
+``tshark -i <network interface name> -f "dst port 9180"``
+
+For example:
+
+.. code-block:: shell
+
+ tshark -i eth0 -f "dst port 9180"
+
+Capture from Scylla node towards Scylla monitor server.
+
+Scylla is running.
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 66 59212 > 9180 [ACK] Seq=317 Ack=78193 Win=158080 Len=0 TSval=79869679 TSecr=3347447210
+
+Scylla is not running
+
+.. code-block:: shell
+
+ Monitor ip Scylla node ip
+ 199.203.229.89 -> 172.16.12.142 TCP 74 60440 > 9180 [SYN] Seq=0 Win=29200 Len=0 MSS=1460 SACK_PERM=1 TSval=79988291 TSecr=0 WS=128
+
+
diff --git a/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitor-without-docker.2.1.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitor.png b/docs/operating-scylla/monitoring/2.3/monitor.png
--- a/docs/operating-scylla/monitoring/2.3/monitor.png
+++ b/docs/operating-scylla/monitoring/2.3/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.3/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst b/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/2.3/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/1.png b/docs/operating-scylla/monitoring/2.4/1.png
--- a/docs/operating-scylla/monitoring/2.4/1.png
+++ b/docs/operating-scylla/monitoring/2.4/1.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/2.png b/docs/operating-scylla/monitoring/2.4/2.png
--- a/docs/operating-scylla/monitoring/2.4/2.png
+++ b/docs/operating-scylla/monitoring/2.4/2.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/3.png b/docs/operating-scylla/monitoring/2.4/3.png
--- a/docs/operating-scylla/monitoring/2.4/3.png
+++ b/docs/operating-scylla/monitoring/2.4/3.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/4.png b/docs/operating-scylla/monitoring/2.4/4.png
--- a/docs/operating-scylla/monitoring/2.4/4.png
+++ b/docs/operating-scylla/monitoring/2.4/4.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf b/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
--- a/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
+++ b/docs/operating-scylla/monitoring/2.4/Scylla_Monitoring_CheatSheet.pdf
null
diff --git a/docs/operating-scylla/monitoring/2.4/alertmanager.png b/docs/operating-scylla/monitoring/2.4/alertmanager.png
--- a/docs/operating-scylla/monitoring/2.4/alertmanager.png
+++ b/docs/operating-scylla/monitoring/2.4/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/cql-optimization.rst b/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/2.4/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png b/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/2.4/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/grafana.png b/docs/operating-scylla/monitoring/2.4/grafana.png
--- a/docs/operating-scylla/monitoring/2.4/grafana.png
+++ b/docs/operating-scylla/monitoring/2.4/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/index.rst b/docs/operating-scylla/monitoring/2.4/index.rst
--- a/docs/operating-scylla/monitoring/2.4/index.rst
+++ b/docs/operating-scylla/monitoring/2.4/index.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst b/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/2.4/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst b/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
--- a/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitor-without-docker.2.1.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitor.png b/docs/operating-scylla/monitoring/2.4/monitor.png
--- a/docs/operating-scylla/monitoring/2.4/monitor.png
+++ b/docs/operating-scylla/monitoring/2.4/monitor.png
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst b/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst b/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/2.4/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst b/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/2.4/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/1.png b/docs/operating-scylla/monitoring/3.0/1.png
--- a/docs/operating-scylla/monitoring/3.0/1.png
+++ b/docs/operating-scylla/monitoring/3.0/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/2.png b/docs/operating-scylla/monitoring/3.0/2.png
--- a/docs/operating-scylla/monitoring/3.0/2.png
+++ b/docs/operating-scylla/monitoring/3.0/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/3.png b/docs/operating-scylla/monitoring/3.0/3.png
--- a/docs/operating-scylla/monitoring/3.0/3.png
+++ b/docs/operating-scylla/monitoring/3.0/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/4.png b/docs/operating-scylla/monitoring/3.0/4.png
--- a/docs/operating-scylla/monitoring/3.0/4.png
+++ b/docs/operating-scylla/monitoring/3.0/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/alertmanager.png b/docs/operating-scylla/monitoring/3.0/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.0/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.0/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/cql-optimization.rst b/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.0/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.0/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/grafana.png b/docs/operating-scylla/monitoring/3.0/grafana.png
--- a/docs/operating-scylla/monitoring/3.0/grafana.png
+++ b/docs/operating-scylla/monitoring/3.0/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.0/index.rst b/docs/operating-scylla/monitoring/3.0/index.rst
--- a/docs/operating-scylla/monitoring/3.0/index.rst
+++ b/docs/operating-scylla/monitoring/3.0/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.0/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.0/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.0/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/1.png b/docs/operating-scylla/monitoring/3.1/1.png
--- a/docs/operating-scylla/monitoring/3.1/1.png
+++ b/docs/operating-scylla/monitoring/3.1/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/2.png b/docs/operating-scylla/monitoring/3.1/2.png
--- a/docs/operating-scylla/monitoring/3.1/2.png
+++ b/docs/operating-scylla/monitoring/3.1/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/3.png b/docs/operating-scylla/monitoring/3.1/3.png
--- a/docs/operating-scylla/monitoring/3.1/3.png
+++ b/docs/operating-scylla/monitoring/3.1/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/4.png b/docs/operating-scylla/monitoring/3.1/4.png
--- a/docs/operating-scylla/monitoring/3.1/4.png
+++ b/docs/operating-scylla/monitoring/3.1/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/alertmanager.png b/docs/operating-scylla/monitoring/3.1/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.1/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.1/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/cql-optimization.rst b/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.1/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.1/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/grafana.png b/docs/operating-scylla/monitoring/3.1/grafana.png
--- a/docs/operating-scylla/monitoring/3.1/grafana.png
+++ b/docs/operating-scylla/monitoring/3.1/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.1/index.rst b/docs/operating-scylla/monitoring/3.1/index.rst
--- a/docs/operating-scylla/monitoring/3.1/index.rst
+++ b/docs/operating-scylla/monitoring/3.1/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.1/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.1/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.1/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/1.png b/docs/operating-scylla/monitoring/3.2/1.png
--- a/docs/operating-scylla/monitoring/3.2/1.png
+++ b/docs/operating-scylla/monitoring/3.2/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/2.png b/docs/operating-scylla/monitoring/3.2/2.png
--- a/docs/operating-scylla/monitoring/3.2/2.png
+++ b/docs/operating-scylla/monitoring/3.2/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/3.png b/docs/operating-scylla/monitoring/3.2/3.png
--- a/docs/operating-scylla/monitoring/3.2/3.png
+++ b/docs/operating-scylla/monitoring/3.2/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/4.png b/docs/operating-scylla/monitoring/3.2/4.png
--- a/docs/operating-scylla/monitoring/3.2/4.png
+++ b/docs/operating-scylla/monitoring/3.2/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/alerting.rst b/docs/operating-scylla/monitoring/3.2/alerting.rst
--- a/docs/operating-scylla/monitoring/3.2/alerting.rst
+++ b/docs/operating-scylla/monitoring/3.2/alerting.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/alertmanager.png b/docs/operating-scylla/monitoring/3.2/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.2/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.2/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/cql-optimization.rst b/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.2/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.2/cql_optimization_master.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/grafana.png b/docs/operating-scylla/monitoring/3.2/grafana.png
--- a/docs/operating-scylla/monitoring/3.2/grafana.png
+++ b/docs/operating-scylla/monitoring/3.2/grafana.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/index.rst b/docs/operating-scylla/monitoring/3.2/index.rst
--- a/docs/operating-scylla/monitoring/3.2/index.rst
+++ b/docs/operating-scylla/monitoring/3.2/index.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst b/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
--- a/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
+++ b/docs/operating-scylla/monitoring/3.2/min-prod-hw.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst b/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
--- a/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitor-troubleshoot.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst b/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
--- a/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitor-without-docker.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst b/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
--- a/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitoring-apis.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst b/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
--- a/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
+++ b/docs/operating-scylla/monitoring/3.2/monitoring-stack.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/monitoring_stack.png b/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
--- a/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
+++ b/docs/operating-scylla/monitoring/3.2/monitoring_stack.png
null
diff --git a/docs/operating-scylla/monitoring/3.2/start-all.rst b/docs/operating-scylla/monitoring/3.2/start-all.rst
--- a/docs/operating-scylla/monitoring/3.2/start-all.rst
+++ b/docs/operating-scylla/monitoring/3.2/start-all.rst
null
diff --git a/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst b/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
--- a/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
+++ b/docs/operating-scylla/monitoring/3.2/updating-dashboard.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/1.png b/docs/operating-scylla/monitoring/3.3/1.png
--- a/docs/operating-scylla/monitoring/3.3/1.png
+++ b/docs/operating-scylla/monitoring/3.3/1.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/2.png b/docs/operating-scylla/monitoring/3.3/2.png
--- a/docs/operating-scylla/monitoring/3.3/2.png
+++ b/docs/operating-scylla/monitoring/3.3/2.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/3.png b/docs/operating-scylla/monitoring/3.3/3.png
--- a/docs/operating-scylla/monitoring/3.3/3.png
+++ b/docs/operating-scylla/monitoring/3.3/3.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/4.png b/docs/operating-scylla/monitoring/3.3/4.png
--- a/docs/operating-scylla/monitoring/3.3/4.png
+++ b/docs/operating-scylla/monitoring/3.3/4.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/alerting.rst b/docs/operating-scylla/monitoring/3.3/alerting.rst
--- a/docs/operating-scylla/monitoring/3.3/alerting.rst
+++ b/docs/operating-scylla/monitoring/3.3/alerting.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/alertmanager.png b/docs/operating-scylla/monitoring/3.3/alertmanager.png
--- a/docs/operating-scylla/monitoring/3.3/alertmanager.png
+++ b/docs/operating-scylla/monitoring/3.3/alertmanager.png
null
diff --git a/docs/operating-scylla/monitoring/3.3/cql-optimization.rst b/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
--- a/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
+++ b/docs/operating-scylla/monitoring/3.3/cql-optimization.rst
null
diff --git a/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png b/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
--- a/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
+++ b/docs/operating-scylla/monitoring/3.3/cql_optimization_master.png
null
Commit Bot
<bot@cloudius-systems.com>Jul 11, 2022, 4:16:05 PM7/11/22
to scylladb-dev@googlegroups.com, Anna Stuchlik
Branch: master
Reply all
Reply to author
Forward
0 new messages