From 19db428811aa56e38338a977eeda81d95953a2a7 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Wed, 2 Jul 2025 16:18:18 +0100 Subject: [PATCH 1/6] This change has been made to ensure the new anywhere-footnote setup works correctly. Signed-off-by: Ray Offiah --- .../buckets-memory-and-storage/storage-engines.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc index 83e6dbd97f..a4c021ab20 100644 --- a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc @@ -5,6 +5,8 @@ {description} It is important to understand which backend storage is best suited to your requirements. +:magma-support-note-fn: If these services are required in versions prior to 7.1.2, Couchstore should be used. +:magma-memory-requirements-fn: Magma's minimum memory requirement is higher at 1GB per node due to the more complex data structures it has to maintain. == Couchstore Couchstore is the default bucket storage engine. @@ -38,11 +40,10 @@ For example, if a node is holding 5{nbsp}TB of data, Magma can be used with only |Query, Index, XDCR, Backup |*Version 7.1.2 and Higher* -|[[magma-support-ref]]Search, Eventing, Analytics<> +|[[magma-support-ref]]Search, Eventing, Analytics{empty}afnote:magma-support-fns[{magma-support-note-fn}] |=== -[horizontal] -[[magma-support-note]]<>:: If these services are required in versions prior to 7.1.2, Couchstore should be used. +afnote:magma-support-fns[omit-separator=true] == Couchstore and Magma at a Glance @@ -51,7 +52,7 @@ For example, if a node is holding 5{nbsp}TB of data, Magma can be used with only | Minimum bucket memory quota | 100{nbsp}MB -| [[quota-ref]]1{nbsp}GB<> +| [[quota-ref]]1{nbsp}GB{empty}afnote:mem-req-fns[{magma-memory-requirements-fn}] | Minimum memory to data ratio | 10% @@ -62,8 +63,7 @@ For example, if a node is holding 5{nbsp}TB of data, Magma can be used with only | 10{nbsp}TB |=== -[horizontal] -[[quota-note]]<>:: Magma's minimum memory requirement is higher at 1GB per node due to the more complex data structures it has to maintain. +afnote:mem-req-fns[omit-separator=true] == When should you use Couchstore? From 20e59e3f5224425692c19c864e320ca7165c0be2 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Thu, 3 Jul 2025 08:17:40 +0100 Subject: [PATCH 2/6] Tidying up Signed-off-by: Ray Offiah --- .../pages/buckets-memory-and-storage/storage-engines.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc index a4c021ab20..c0e0c75df5 100644 --- a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc @@ -21,10 +21,10 @@ If you have a small data set that can fit in memory, then you should consider us Magma is designed for high performance with very large datasets that do not fit in memory. It is ideal for use cases that rely primarily on disk access. -The performance of disk access will be as good as the underlying disk sub-systems -- +The performance of disk access will be as good as the underlying disk subsystems -- for example, using NVMe SSDs will give higher performance. -In order to get maximum performance from Magma for disk-oriented workloads, it is recommended to set the Writer Threads to `Disk i/o optimized`. This setting will ensure there are enough threads to sustain high write rates. +To get maximum performance from Magma for disk-oriented workloads, it is recommended to set the Writer Threads to `Disk i/o optimized`. This setting will ensure there are enough threads to sustain high write rates. To learn more about Writer Thread settings, see xref:manage:manage-settings/general-settings.adoc#data-settings[Data Settings] From 9b819796e04376311defee5b3fa54b8c1530cd40 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Mon, 7 Jul 2025 08:53:46 +0100 Subject: [PATCH 3/6] Tidying up: added `:afnote-omit-separators` attribute. Signed-off-by: Ray Offiah --- .../learn/pages/buckets-memory-and-storage/storage-engines.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc index c0e0c75df5..fa0ad8af78 100644 --- a/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/storage-engines.adoc @@ -5,6 +5,7 @@ {description} It is important to understand which backend storage is best suited to your requirements. +:afnote-omit-separators: true :magma-support-note-fn: If these services are required in versions prior to 7.1.2, Couchstore should be used. :magma-memory-requirements-fn: Magma's minimum memory requirement is higher at 1GB per node due to the more complex data structures it has to maintain. == Couchstore From d9aef7dcde3ecd141607c5198d26a16e2d68ac62 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Mon, 14 Jul 2025 08:07:11 +0100 Subject: [PATCH 4/6] Tidying up: updated footnotes to use `afnote` references where applicable. Signed-off-by: Ray Offiah --- modules/install/pages/install-ports.adoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/modules/install/pages/install-ports.adoc b/modules/install/pages/install-ports.adoc index d4b1deebc5..2e0a42bbbd 100644 --- a/modules/install/pages/install-ports.adoc +++ b/modules/install/pages/install-ports.adoc @@ -4,6 +4,10 @@ :fn-encrypted-traffic-port: footnote:fn-encrypted-traffic-port[The Cluster Management Exchange encrypted port 21250 is not currently used, but is reserved for future use.] :fn-encrypted-communication-port: footnote:fn-encrypted-communication-port[The Cluster Management Exchange encrypted port 21350 is not currently used, but is reserved for future use.] +:afnote-eventing-debug-port: afnote:table-2[The Eventing Service Debugger port `eventing_debug_port` (9140) is an internal port and is not supported for external access outside of the cluster. You should only use this port in your development environments.] +:afnote-encrypted-traffic-port: afnote:table-2[The Cluster Management Exchange encrypted port 21250 is not currently used, but is reserved for future use., refid=encrypted-traffic] +:afnote-encrypted-communication-port: afnote:table-2[The Cluster Management Exchange encrypted port 21350 is not currently used, but is reserved for future use., refid=encrypted-comms] + [abstract] {description} These ports must be open for Couchbase Server to operate correctly. @@ -72,7 +76,7 @@ The following table lists all port numbers, grouped by category of communication | _Node-local only_ | *Unencrypted*: 9119, 9998, 11213, 21200, 21300 -*Encrypted*: 21250 {fn-encrypted-traffic-port}, 21350 {fn-encrypted-communication-port} +*Encrypted*: 21250 {afnote-encrypted-traffic-port}, 21350 {afnote-encrypted-communication-port} | _Node-to-node_ | *Unencrypted*: 4369, 8091-8094, 9100-9105, 9110-9118, 9120-9122, 9130, 9999, 11209-11210, 21100 @@ -80,7 +84,7 @@ The following table lists all port numbers, grouped by category of communication *Encrypted*: 9999, 11206, 11207, 18091-18094, 19102, 19130, 21150 | _Client-to-node_ -| *Unencrypted*: 8091-8097, 9123, 9140 {fn-eventing-debug-port}, 11210, 11280 +| *Unencrypted*: 8091-8097, 9123, 9140 {afnote-eventing-debug-port}, 11210, 11280 *Encrypted*: 11207, 18091-18097 @@ -135,7 +139,7 @@ The following table contains a detailed description of each port used by Couchba | Client-to-node | XDCR (cluster-to-cluster) -| `epmd` footnote:fn-cannot-remap[This port cannot be remapped.] +| `epmd`{empty}afnote:table-2[This port cannot be remapped.] | 4369 | Erlang Port Mapper Daemon | Yes @@ -405,7 +409,7 @@ a| Search Service gRPC port used for xref:learn:services-and-indexes/services/se | No | No -| Cluster Management Exchange footnote:fn-encrypted-traffic-port[] +| Cluster Management Exchange{empty}afnote:table-2[refid=encrypted-traffic] | 21200 / 21250 | Cluster management traffic and communication @@ -414,7 +418,7 @@ a| Search Service gRPC port used for xref:learn:services-and-indexes/services/se | No | No -| Cluster Management Exchange footnote:fn-encrypted-communication-port[] +| Cluster Management Exchange{empty} afnote:table-2[refid=encrypted-comms] | 21300 / 21350 | Cluster management traffic and communication @@ -424,6 +428,8 @@ a| Search Service gRPC port used for xref:learn:services-and-indexes/services/se | No |=== +afnote:table-2[] + [#map-custom-ports] == Custom Port Mapping From 3c685f79797e283d10af9842366e6ffec6ba5e78 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Mon, 14 Jul 2025 09:30:26 +0100 Subject: [PATCH 5/6] Tidying up: adjusted formatting, improved grammar, and updated `afnote` references for consistency. Signed-off-by: Ray Offiah --- modules/install/pages/install-ports.adoc | 47 ++++++++++++++---------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/modules/install/pages/install-ports.adoc b/modules/install/pages/install-ports.adoc index 2e0a42bbbd..d2922f597d 100644 --- a/modules/install/pages/install-ports.adoc +++ b/modules/install/pages/install-ports.adoc @@ -1,10 +1,8 @@ = Couchbase Server Ports + :description: Couchbase Server uses multiple TCP ports to facilitate communication between server components, as well as with Couchbase clients. -:fn-eventing-debug-port: pass:n[footnote:fn-eventing-debug-port[pass:n[The Eventing Service Debugger port `eventing_debug_port` (9140) is an internal port and is not supported for external access outside of the cluster. You should only use this port in your development environments.\]]] -:fn-encrypted-traffic-port: footnote:fn-encrypted-traffic-port[The Cluster Management Exchange encrypted port 21250 is not currently used, but is reserved for future use.] -:fn-encrypted-communication-port: footnote:fn-encrypted-communication-port[The Cluster Management Exchange encrypted port 21350 is not currently used, but is reserved for future use.] -:afnote-eventing-debug-port: afnote:table-2[The Eventing Service Debugger port `eventing_debug_port` (9140) is an internal port and is not supported for external access outside of the cluster. You should only use this port in your development environments.] +:afnote-eventing-debug-port: afnote:table-2[The Eventing Service Debugger port `eventing_debug_port` (9140) is an internal port and is not supported for external access outside of the cluster. You should only use this port in your development environments., refid=eventing-debug-port] :afnote-encrypted-traffic-port: afnote:table-2[The Cluster Management Exchange encrypted port 21250 is not currently used, but is reserved for future use., refid=encrypted-traffic] :afnote-encrypted-communication-port: afnote:table-2[The Cluster Management Exchange encrypted port 21350 is not currently used, but is reserved for future use., refid=encrypted-comms] @@ -16,11 +14,14 @@ These ports must be open for Couchbase Server to operate correctly. This page describes the TCP ports that are used by Couchbase Server for network communication. Some ports, such as those used for cluster management, are required to be open on every node because they are essential to how Couchbase Server communicates with itself. -Other ports are used by individual xref:learn:services-and-indexes/services/services.adoc[Couchbase Services], and are only required to be open on the nodes where those services are running. +Other ports are used by individual xref:learn:services-and-indexes/services/services.adoc[Couchbase Services] and are only required to be open on the nodes where those services are running. Couchbase Server uses a default set of port numbers for all ports that it requires. -The xref:learn:clusters-and-availability/cluster-manager.adoc[Couchbase Cluster Manager] on each node is responsible for port management, and will open and close these ports on the host as necessary, as well as automatically switch to using encrypted ports if the cluster is configured to use TLS. -Most port numbers can be <> to fit the requirements of your network environment, but some port numbers cannot be changed. +The xref:learn:clusters-and-availability/cluster-manager.adoc[Couchbase Cluster Manager] on each node is responsible for port management. +It will open and close these ports on the host as necessary, +as well as automatically switch to using encrypted ports if the cluster is configured to use TLS. +Most port numbers can be <> to fit the requirements of your network environment, +but some port numbers cannot be changed. IMPORTANT: If other software on the same host is using any of the ports that are required by Couchbase Server, then Couchbase Server will not function properly and may fail to start. Refer to <> below. @@ -29,8 +30,12 @@ Refer to <> below. An _ephemeral_ port is one temporarily allocated by a server's operating system, as the source for an outgoing communication. Each operating system provides a default range of port numbers that can be assigned to ephemeral ports, when necessary. -For Linux distributions, the typical range is 32768-61000. -Couchbase Server relies on the _full_ default range provided by each operating system: therefore, the default range should _not_ be reduced by the administrator; since the resulting lack of ephemeral ports may result in outgoing communications using _well-known_ ports instead (for example, _8091_); thereby preventing Couchbase-Server processes from binding to the well-known ports to which they are assigned. +For Linux distributions, the typical range is 32768–61000. +Couchbase Server relies on the _full_ default range provided by each operating system: +therefore, the default range should _not_ be reduced by the administrator; +since the resulting lack of ephemeral ports may result in outgoing communications using _well-known_ ports instead, +(for example, _8091_); +thereby preventing Couchbase-Server processes from binding to the well-known ports to which they are assigned. === Couchbase Server Communication Paths @@ -84,21 +89,22 @@ The following table lists all port numbers, grouped by category of communication *Encrypted*: 9999, 11206, 11207, 18091-18094, 19102, 19130, 21150 | _Client-to-node_ -| *Unencrypted*: 8091-8097, 9123, 9140 {afnote-eventing-debug-port}, 11210, 11280 +| *Unencrypted*: 8091–8097, 9123, 9140 {afnote-eventing-debug-port}, 11210, 11280 -*Encrypted*: 11207, 18091-18097 +*Encrypted*: 11207, 18091–18097 | _XDCR (cluster-to-cluster)_ a| * Version 2 (XMEM) ** *Unencrypted*: 8091, 8092, 11210 ** *Encrypted*: 11207, 18091, 18092 -NOTE: If enforcing TLS encryption, these ports may be blocked outside of a Couchbase Server cluster but need to remain open between nodes. +NOTE: If enforcing TLS encryption, +these ports may be blocked outside a Couchbase Server cluster but need to remain open between nodes. | _cbbackupmgr (backup/restore client)_ -a| *Unencrypted*: 8091-8096, 9102, 11210 +a| *Unencrypted*: 8091–8096, 9102, 11210 -*Encrypted*: 11207, 18091-18096, 19102 +*Encrypted*: 11207, 18091–18096, 19102 [NOTE] ==== @@ -358,7 +364,7 @@ a| Search Service gRPC port used for xref:learn:services-and-indexes/services/se | No | No -| `eventing_debug_port` footnote:fn-eventing-debug-port[] +| `eventing_debug_port` afnote:table-2[refid=eventing-debug-port] | 9140 | Eventing Service Debugger | No @@ -383,7 +389,7 @@ a| Search Service gRPC port used for xref:learn:services-and-indexes/services/se | `memcached_dedicated_port` / `memcached_dedicated_ssl_port` | 11209 / 11206 -| Data Service and ns_server. Used for important control-commands; e.g. creation of buckets and vBuckets, and compaction. +| Data Service and ns_server. Used for important control-commands; e.g., creation of buckets and vBuckets, and compaction. | Yes | No | No @@ -443,7 +449,7 @@ WARNING: Changing port mappings should only be done at the time of initial node/ .To Change Port Mapping . xref:install-intro.adoc[Install Couchbase Server]. . xref:startup-shutdown.adoc[Stop the Couchbase Server service]. -. For most ports, you'll need to edit the Couchbase Server [.path]_static_config_ file. +. For most ports, you will need to edit the Couchbase Server [.path]_static_config_ file. (This will be wherever you put the path to [.path]_/couchbase/etc/couchbase/static_config_ in multi-node installations.) + [source,console] @@ -451,7 +457,8 @@ WARNING: Changing port mappings should only be done at the time of initial node/ vi /opt/couchbase/etc/couchbase/static_config ---- + -If you're remapping the CAPI port (8092 / 18092) you'll need to edit the [.path]_/opt/couchbase/etc/couchdb/default.d/capi.ini_ file and replace 8092 with the new port number. +If you are remapping the CAPI port (8092 / 18092), +you will need to edit the [.path]_/opt/couchbase/etc/couchdb/default.d/capi.ini_ file and replace 8092 with the new port number. . Add each custom port map entry on its own line, using the following format (enclosed in braces and terminated by a period): + [source,console,subs=+quotes] @@ -466,8 +473,8 @@ For example, to change the REST API port from 8091 to 9000, you would add the fo {rest_port, 9000}. ---- + -Once you've added all of your custom port mappings, save the file and close your text editor. -. If Couchbase Server was previously configured, you'll need to delete the [.path]_/opt/couchbase/var/lib/couchbase/config/config.dat_ file and files in the [.path]_/opt/couchbase/var/lib/couchbase/config/chronicle/_ directory to remove the old configuration. +Once you have added all of your custom port mappings, save the file and close your text editor. +. If Couchbase Server was previously configured, you will need to delete the [.path]_/opt/couchbase/var/lib/couchbase/config/config.dat_ file and files in the [.path]_/opt/couchbase/var/lib/couchbase/config/chronicle/_ directory to remove the old configuration. + [source,console] ---- From 6a62200bd83de87e51a7a39100c6fbd46f8fff40 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Thu, 24 Jul 2025 17:06:54 +0100 Subject: [PATCH 6/6] Tidying up: updated footnotes to use `afnote` syntax and added missing `afnote::table-1[]` reference. Signed-off-by: Ray Offiah --- modules/install/pages/install-platforms.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/install/pages/install-platforms.adoc b/modules/install/pages/install-platforms.adoc index c81cdf9549..3d17fe107c 100644 --- a/modules/install/pages/install-platforms.adoc +++ b/modules/install/pages/install-platforms.adoc @@ -33,8 +33,7 @@ a|* AL2023 (x86-64, ARM64) a| * 12.x * 11.x -| Oracle Linux{empty}footnote:[Only the Red Hat Compatible Kernel (RHCK) is supported. -The Unbreakable Enterprise Kernel (UEK) is not supported.] +| Oracle Linux{empty}afnote:table-1[Only the Red Hat Compatible Kernel (RHCK) is supported. The Unbreakable Enterprise Kernel (UEK) is not supported.] a|* 9.x * 8.x @@ -62,6 +61,8 @@ a|* 2022 |=== +afnote::table-1[] + .Supported Operating Systems for Development and Testing Only [cols="100,135",options="header"] |===