From 62e46257d5238f5f72e094290e37951e0ba7d775 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 29 Apr 2024 13:36:29 -0400 Subject: [PATCH 01/16] Initial pass at What's new update --- modules/introduction/pages/whats-new.adoc | 9 ++++++++- modules/introduction/partials/new-features-76_2.adoc | 8 ++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 modules/introduction/partials/new-features-76_2.adoc diff --git a/modules/introduction/pages/whats-new.adoc b/modules/introduction/pages/whats-new.adoc index 0d17f4dc03..4802aef775 100644 --- a/modules/introduction/pages/whats-new.adoc +++ b/modules/introduction/pages/whats-new.adoc @@ -8,8 +8,15 @@ For information about platform support changes, deprecation notifications, notable improvements, and fixed and known issues, refer to the xref:release-notes:relnotes.adoc[Release Notes]. +[#new-features-7.6.2] +== New Features and Enhancements in 7.6.2 + +The following new features are provided in this release. + +include::partial$new-features-76_2.adoc[] + [#new-features] -== New Features and Enhancements +== New Features and Enhancements in 7.6.0 The following new features are provided in this release. diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc new file mode 100644 index 0000000000..4b32c37cf0 --- /dev/null +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -0,0 +1,8 @@ +=== Backup + +* The xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: + +** `/api/v1/cluster/self/repository/active` +** `/api/v1/plan/PLAN-NAME` +** `/api/v1/cluster/self/repository/active/JOB-NAME/taskHistory` + From dab2a7a539badd5a7e73a95c33e1f6616848b54f Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 30 Apr 2024 09:05:54 -0400 Subject: [PATCH 02/16] Interim checkin while switching tasks --- .../partials/new-features-76_2.adoc | 9 +- modules/learn/pages/security/roles.adoc | 157 +++++++++--------- 2 files changed, 88 insertions(+), 78 deletions(-) diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index 4b32c37cf0..853bff2d62 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -1,8 +1,9 @@ === Backup -* The xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: +* Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: + +** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active`] +** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active/JOB-NAME/taskHistory`] +** xref:rest-api:backup-get-plan-info.adoc[`/plan/PLAN-NAME`] -** `/api/v1/cluster/self/repository/active` -** `/api/v1/plan/PLAN-NAME` -** `/api/v1/cluster/self/repository/active/JOB-NAME/taskHistory` diff --git a/modules/learn/pages/security/roles.adoc b/modules/learn/pages/security/roles.adoc index 56fd02c248..3f89c7c1b2 100644 --- a/modules/learn/pages/security/roles.adoc +++ b/modules/learn/pages/security/roles.adoc @@ -1,5 +1,5 @@ = Roles -:description: pass:q[A Couchbase _role_ permits one or more _resources_ to be accessed according to defined _privileges_.] +:description: pass:q[A Couchbase role permits one or more resources to be accessed according to defined privileges.] :page-aliases: security:security-roles,security:concepts-rba,security:concepts-rba-for-apps,security:rbac-ro-user,learn:security/resources-under-access-control,security:security-resources-under-access-control [abstract] @@ -8,27 +8,27 @@ [#roles-and-privileges] == Roles and Privileges -Couchbase _roles_ each have a fixed association with a set of one or more privileges. +Couchbase roles each have a fixed association with a set of one or more privileges. Each privilege is associated with a resource. Privileges are actions such as *Read*, *Write*, *Execute*, *Manage*, *Flush*, and *List*; or a combination of some or all of these. Roles are of the following kinds: -* _Administative_: Associated with cluster-wide privileges. +* Administative: Associated with cluster-wide privileges. Some of these roles are for administrators; who might manage cluster-configurations; or read statistics; or enforce security. Others are for users and user-defined applications that require access to specific, cluster-wide resources. -* _Bucket_: Associated with bucket administration, collection management, and application access. +* Bucket: Associated with bucket administration, collection management, and application access. Roles in this category can each be applied to one, to multiple, or to all buckets on the cluster. -* _Data_, _Views_, and _XDCR_: Associated with the Data Service. -This includes the reading, writing, monitoring, backing-up, and restoring of data; the administration of Views; and the administration of _Cross Data-Center Replication_ (XDCR). +* Data, Views, and XDCR: Associated with the Data Service. +This includes the reading, writing, monitoring, backing-up, and restoring of data; the administration of Views; and the administration of Cross Data-Center Replication (XDCR). -* _Other Services_: Roles for the administration of services other than the Data Service. -These roles are organized under the following categories: _Query & Index_, _Search_, _Analytics_, and _Backup_. -(_Eventing_ administration is covered within the _Administrative_ category.) +* Other Services: Roles for the administration of services other than the Data Service. +These roles are organized under the following categories: Query & Index, Search, Analytics, and Backup. +(Eventing administration is covered within the Administrative category.) -* _Mobile_: Associated with the administration of _Sync Gateway_. +* Mobile: Associated with the administration of Sync Gateway. When a user (meaning either an administrator or an application) attempts to access a resource, they must authenticate. The roles and privileges associated with the user-credentials thereby presented are checked by Couchbase Server. @@ -40,21 +40,21 @@ If the associated roles contain privileges that support the kind of access that All data within a bucket is contained within some collection, within some scope. Permissions conveyed by bucket-related roles may be restricted in any of the following ways: -* By _Bucket_: Permissions apply to all data in the specified bucket: all scopes and collections are thus covered by the permissions. +* By Bucket: Permissions apply to all data in the specified bucket: all scopes and collections are thus covered by the permissions. -* By _Bucket_ and _Scope_: Permissions apply only to the collections within the specified scope (or scopes), within the specified bucket. +* By Bucket and Scope: Permissions apply only to the collections within the specified scope (or scopes), within the specified bucket. -* By _Bucket_, _Scope_, and _Collection_: Permissions apply only to the data within the specified collection (or collections), within the specified scope (or scopes), within the specified bucket. +* By Bucket, Scope, and Collection: Permissions apply only to the data within the specified collection (or collections), within the specified scope (or scopes), within the specified bucket. For detailed information on scopes and collections, see xref:learn:data/scopes-and-collections.adoc[Scopes and Collections]. [#commonly-used-roles] === Commonly Used Roles -Couchbase Server _users_ can largely be categorized as _administrators_, _developers_, and _applications_. +Couchbase Server users can largely be categorized as administrators, developers, and applications. Each user-category is supported by a different subset of roles. -* _Administrators_. +* Administrators. Able to log into Couchbase Web Console and perform administrative tasks; but unable to read or write data. + The administrative tasks available are divided into multiple `admin` roles. @@ -62,19 +62,19 @@ For example, the *Cluster Admin* role allows the management of all cluster featu See the *Admin* roles listed below for full details. Note that depending on the administrator's assigned roles, the content of Couchbase Web Console changes: for example, the entire *Security* screen is only visible to *Full Admin* administrators; and to administrators who possess both the *Local User Security Admin* and the *External User Security Admin* roles. -* _Applications_. +* Applications. Able to read or write data; but unable to log into Couchbase Web Console, or in any way modify cluster-settings. For example, the *Data Reader* and *Data Writer* roles allows data to be respectively read and written to one or more collections, within one or more scopes, within one or more buckets. Other application-intended roles are *Application Access*, *Data Writer*, *Data Backup & Restore*, and *Data Monitor*. See below for details on each. -* _Developers_. +* Developers. Can be given a selection of roles, allowing the right degree of data and console access. For example, the *Read-Only Admin* role allows the reading of cluster-statistics, while the *Data Read* and *Data Write* roles allow access to data on one or more buckets. -The following list contains all roles supported by Couchbase Server, _Enterprise Edition_. +The following list contains all roles supported by Couchbase Server, Enterprise Edition. Each role is explained by means of a description and (in most cases) a table: the table lists the privileges in association with resources. -The header of each table states the role's *name*, followed by its _alias name_ in parentheses: alias names are used in commands and queries. +The header of each table states the role's *name*, followed by its alias name in parentheses: alias names are used in commands and queries. In each table-body, where a privilege is associated with a resource, this is indicated with a check-mark. Where a privilege is not associated with a resource (or where association would not be applicable), this is indicated with a cross. Resources not referred to in a particular table have no privileges associated with them in the context of the role being described. @@ -88,15 +88,15 @@ See xref:manage:manage-logging/manage-logging.adoc[Manage Logging], for detailed [#full-admin] == Full Admin -The *Full Admin* role (an _Administrative_ role) supports full access to all Couchbase-Server features and resources, including those of security. +The *Full Admin* role (an Administrative role) supports full access to all Couchbase-Server features and resources, including those of security. The role allows access to Couchbase Web Console, and allows the reading and writing of bucket-data. -This role is also available in Couchbase Server _Community Edition_. +This role is also available in Couchbase Server Community Edition. [#cluster-admin] == Cluster Admin -The *Cluster Admin* role (an _Administrative_ role) allows the management of all cluster features except security. +The *Cluster Admin* role (an Administrative role) allows the management of all cluster features except security. The role allows access to Couchbase Web Console, but does not permit the writing of data. [#table_cluster_admin_role,cols="15,8,8,8,8",hrows=3] @@ -139,7 +139,7 @@ The role allows access to Couchbase Web Console, but does not permit the writing [#local-user-security-admin] == Local User Security Admin -The *Local User Security Admin* role (an _Administrative_ role) allows the management of local user roles and the reading of all cluster statistics. +The *Local User Security Admin* role (an Administrative role) allows the management of local user roles and the reading of all cluster statistics. The role does not permit the granting of the *Full Admin*, the *Read-Only Admin*, the *Local User Security Admin*, or the *External User Security Admin* role; and does not permit the administrator to change their own role (which therefore remains *Local User Security Admin*). The role supports access to Couchbase Web Console, but does not support the reading of data. @@ -183,7 +183,7 @@ The role supports access to Couchbase Web Console, but does not support the read [#external-user-security-admin] == External User Security Admin -The *External User Security Admin* role (an _Administrative_ role) allows the management of external user roles and the reading of all cluster statistics. +The *External User Security Admin* role (an Administrative role) allows the management of external user roles and the reading of all cluster statistics. The role does not permit the granting of the *Full Admin*, the *Read-Only Admin*, the *Local User Security Admin*, or the *External User Security Admin* role; and does not permit the administrator to change their own role (which therefore remains *External User Security Admin*). The role supports access to Couchbase Web Console, but does not support the reading of data. @@ -227,10 +227,12 @@ The role supports access to Couchbase Web Console, but does not support the read [#read-only-admin] == Read-Only Admin -The *Read-Only Admin* role (an _Administrative_ role) supports the reading of Couchbase Server-statistics: this includes registered usernames with roles and authentication domains, but excludes passwords. -The role allows access to Couchbase Web Console. +The *Read-Only Admin* role (an Administrative role) supports the reading of Couchbase Server statistics. +This information includes registered usernames with roles and authentication domains, but excludes passwords. +Users with this role can also read Backup Service data to monitor backup plans and tasks. +The role allows access to Couchbase Server Web Console. -This role is also available in Couchbase Server _Community Edition_. +This role is also available in Couchbase Server Community Edition. [#table_read_only_admin_role,cols="15,8,8,8,8",hrows=3] |=== @@ -267,12 +269,19 @@ This role is also available in Couchbase Server _Community Edition_. ^| image:introduction/no.png[] ^| image:introduction/no.png[] ^| image:introduction/no.png[] + +^| Backup Service (tasks and plans) +^| image:introduction/yes.png[] +^| image:introduction/no.png[] +^| image:introduction/no.png[] +^| image:introduction/no.png[] + |=== [#external-stats-reader] == External Stats Reader -The *External Stats Reader* role (an _Administrative_ role) grants access to the `/metrics` and `/prometheus_sd_config` endpoints for _Prometheus_ integration. +The *External Stats Reader* role (an Administrative role) grants access to the `/metrics` and `/prometheus_sd_config` endpoints for Prometheus integration. All statistics for all services can be read. The role does not allow access to Couchbase Web Console. @@ -298,7 +307,7 @@ The role does not allow access to Couchbase Web Console. [#xdcr-admin] == XDCR Admin -The *XDCR Admin* role (an _XDCR_ role) allows use of XDCR features, to create cluster references and replication streams. +The *XDCR Admin* role (an XDCR role) allows use of XDCR features, to create cluster references and replication streams. The role allows access to Couchbase Web Console and allows the reading of data. [#table_xdcr_admin_role,cols="15,8,8,8,8",hrows=3] @@ -353,7 +362,7 @@ The role allows access to Couchbase Web Console and allows the reading of data. [#query-curl-access] == Query Curl Access -The *Query Curl Access* role (a _Query & Index_ role) allows the {sqlpp} CURL function to be executed by an externally authenticated user. +The *Query Curl Access* role (a Query & Index role) allows the {sqlpp} CURL function to be executed by an externally authenticated user. The user can access Couchbase Web Console, but cannot read data, other than that returned by the {sqlpp} CURL function. Note that the *Query Curl Access* role should be assigned with caution, since it entails risk: CURL runs within the local Couchbase Server network; therefore, the assignee of the *Query Curl Access* role is permitted to run GET and POST requests on the internal network, while being themselves externally located. @@ -402,7 +411,7 @@ In versions of Couchbase Server prior to 5.5, this role was referred to as *Quer [#query-system-catalog] == Query System Catalog -The *Query System Catalog* role (a _Query & Index_ role) allows information to be looked up by means of {sqlpp} in the system catalog: this includes `system:indexes`, `system:prepareds`, and tables listing current and past queries. +The *Query System Catalog* role (a Query & Index role) allows information to be looked up by means of {sqlpp} in the system catalog: this includes `system:indexes`, `system:prepareds`, and tables listing current and past queries. This role is designed for troubleshooters, who need to debug queries. The role allows access to Couchbase Web Console, but does not permit the reading of bucket-items. @@ -458,7 +467,7 @@ The role allows access to Couchbase Web Console, but does not permit the reading [#manage-global-functions] == Manage Global Functions -The *Manage Global Functions* role (a _Query & Index_ role) allows global {sqlpp} functions to be managed. +The *Manage Global Functions* role (a Query & Index role) allows global {sqlpp} functions to be managed. The user can access Couchbase Web Console, but cannot read data. [#table_manage_global_functions_role,cols="15,8,8,8,8",hrows=3] @@ -495,7 +504,7 @@ The user can access Couchbase Web Console, but cannot read data. [#execute-global-functions] == Execute Global Functions -The *Execute Global Functions* role (a _Query & Index_ role) allows global {sqlpp} functions to be executed. +The *Execute Global Functions* role (a Query & Index role) allows global {sqlpp} functions to be executed. The user can access Couchbase Web Console, but cannot read data. [#table_query_execute_global_functions_role,cols="15,8,8,8,8",hrows=3] @@ -532,7 +541,7 @@ The user can access Couchbase Web Console, but cannot read data. [#manage-scope-functions] == Manage Scope Functions (Query and Index) -The *Manage Scope Functions* role (a _Query & Index_ role) allows {sqlpp} and _user defined_ functions to be managed for a given scope, given corresponding specification of _bucket_. +The *Manage Scope Functions* role (a Query & Index role) allows {sqlpp} and user defined functions to be managed for a given scope, given corresponding specification of bucket. The user can access Couchbase Web Console, but cannot read data. [#table_manage_scope_functions_role,cols="15,8,8,8,8",hrows=3] @@ -569,7 +578,7 @@ The user can access Couchbase Web Console, but cannot read data. [#execute-scope-functions] == Execute Scope Functions -The *Execute Scope Functions* role (a _Query & Index_ role) allows {sqlpp} and _user defined_ functions to be executed for a given scope, given corresponding specification of _bucket_. +The *Execute Scope Functions* role (a Query & Index role) allows {sqlpp} and user defined functions to be executed for a given scope, given corresponding specification of bucket. The user can access Couchbase Web Console, but cannot read data. [#table_execute_scope_functions_role,cols="15,8,8,8,8",hrows=3] @@ -606,7 +615,7 @@ The user can access Couchbase Web Console, but cannot read data. [#manage-global-external-functions] == Manage Global External Functions -The *Manage Global External Functions* role (a _Query & Index_ role) allows global external language functions to be managed. +The *Manage Global External Functions* role (a Query & Index role) allows global external language functions to be managed. The user can access Couchbase Web Console, but cannot read data. [#table_manage_global_external_functions_role,cols="15,8,8,8,8",hrows=3] @@ -643,7 +652,7 @@ The user can access Couchbase Web Console, but cannot read data. [#execute-global-external-functions] == Execute Global External Functions -The *Execute Global External Functions* role (a _Query & Index_ role) allows global {sqlpp} functions to be executed. +The *Execute Global External Functions* role (a Query & Index role) allows global {sqlpp} functions to be executed. The user can access Couchbase Web Console, but cannot read data. [#table_execute_global_external_functions_role,cols="15,8,8,8,8",hrows=3] @@ -680,7 +689,7 @@ The user can access Couchbase Web Console, but cannot read data. [#manage-scope-external-functions] == Manage Scope External Functions -The *Manage Scope External Functions* role (a _Query & Index_ role) allows external language functions to be managed for a given scope, given corresponding specification of _bucket_. +The *Manage Scope External Functions* role (a Query & Index role) allows external language functions to be managed for a given scope, given corresponding specification of bucket. The user can access Couchbase Web Console, but cannot read data. [#table_manage_external_functions_role,cols="15,8,8,8,8",hrows=3] @@ -717,7 +726,7 @@ The user can access Couchbase Web Console, but cannot read data. [#execute-scope-external-functions] == Execute Scope External Functions -The *Execute Scope External Functions* role (a _Query & Index_ role) allows external language functions to be executed for a given scope, given corresponding specification of _bucket_. +The *Execute Scope External Functions* role (a Query & Index role) allows external language functions to be executed for a given scope, given corresponding specification of bucket. The user can access Couchbase Web Console, but cannot read data. [#table_execute_external_functions_role,cols="15,8,8,8,8",hrows=3] @@ -754,7 +763,7 @@ The user can access Couchbase Web Console, but cannot read data. [#analytics-reader] == Analytics Reader -The *Analytics Reader* role (an _Analytics_ role) allows querying of shadow data-sets. +The *Analytics Reader* role (an Analytics role) allows querying of shadow data-sets. The role allows access to Couchbase Web Console, and permits the reading of data. [#table_analytics_reader_role,cols="15,8,8,8,8",hrows=3] @@ -791,7 +800,7 @@ The role allows access to Couchbase Web Console, and permits the reading of data [#analytics-admin] == Analytics Admin -The *Analytics Admin* role (an _Analytics_ role) allows management of dataverses; management of all Analytics Service links; and management of all datasets. +The *Analytics Admin* role (an Analytics role) allows management of dataverses; management of all Analytics Service links; and management of all datasets. The role allows access to Couchbase Web Console, but does not permit the reading of data. [#table_analytics_admin_role,cols="15,8,8,8,8",hrows=3] @@ -840,7 +849,7 @@ The role allows access to Couchbase Web Console, but does not permit the reading [#bucket-admin] == Bucket Admin -The *Bucket Admin* role (which is a _Bucket_ role) allows the management of all _per bucket_ features (including starting and stopping XDCR). +The *Bucket Admin* role (which is a Bucket role) allows the management of all per bucket features (including starting and stopping XDCR). The role allows access to Couchbase Web Console, but does not permit the reading or writing of data. [#table_bucket_admin_role,cols="15,8,8,8,8",hrows=3] @@ -889,7 +898,7 @@ The role allows access to Couchbase Web Console, but does not permit the reading [#manage-scopes] == Manage Scopes -The *Manage Scopes* role (a _Bucket_ role) allows the creation and deletion of scopes, and the creation and deletion of collections _per scope_, given the corresponding specification of _bucket_. +The *Manage Scopes* role (a Bucket role) allows the creation and deletion of scopes, and the creation and deletion of collections per scope, given the corresponding specification of bucket. The role allows no access to data, and does not permit access to Couchbase Web Console. The role is intended for application use only. @@ -921,12 +930,12 @@ The role is intended for application use only. [#application-access] == Application Access -The *Application Access* role (a _Bucket_ role) provides read and write access to data, _per bucket_. +The *Application Access* role (a Bucket role) provides read and write access to data, per bucket. The role does not allow access to Couchbase Web Console: it is intended for applications, rather than users. -Note that this role is also available in the _Community Edition_ of Couchbase Server. +Note that this role is also available in the Community Edition of Couchbase Server. The role is provided in support of buckets that were created on versions of Couchbase Server prior to 5.0. -Such buckets were accessed by specifying _bucket-name_ and _bucket-password_: however, bucket-passwords are not recognized by Couchbase Server 5.0 and after. +Such buckets were accessed by specifying bucket-name and bucket-password: however, bucket-passwords are not recognized by Couchbase Server 5.0 and after. Therefore, for each pre-existing bucket, the upgrade-process for 5.0 and after creates a new user, whose username is identical to the bucket-name; and whose password is identical to the former bucket-password, if one existed. If no bucket-password existed, the user is created with no password. This migration-process allows the same name-combination as before to be used in authentication. @@ -994,7 +1003,7 @@ Note that in versions of Couchbase Server prior to 5.5, this role was referred t [#xdcr-inbound] == XDCR Inbound -The *XDCR Inbound* role (which is an _XDCR_ role) allows the creation of inbound XDCR streams, _per bucket_. +The *XDCR Inbound* role (which is an XDCR role) allows the creation of inbound XDCR streams, per bucket. It does not allow access to Couchbase Web Console, and does not permit the reading of data. In versions of Couchbase Server prior to 5.5, this role was referred to as *Replication Target*. @@ -1039,7 +1048,7 @@ In versions of Couchbase Server prior to 5.5, this role was referred to as *Repl [#sync-gateway] == Sync Gateway -The *Sync Gateway* role (which is a _Mobile_ role) allows full access to data _per bucket_, as required by Sync Gateway. +The *Sync Gateway* role (which is a Mobile role) allows full access to data per bucket, as required by Sync Gateway. The role does not allow access to Couchbase Web Console. The user can, by means of Sync Gateway, read and write data, manage indexes and views, and read some cluster information. @@ -1119,7 +1128,7 @@ The user can, by means of Sync Gateway, read and write data, manage indexes and [#sync-gateway-configurator] == Sync Gateway Architect -The *Sync Gateway Architect* role (which is a _Mobile_ role) allows management of Sync Gateway databases; and of Sync Gateway users and roles; and allows access to Sync Gateway's `/metrics` endpoint. +The *Sync Gateway Architect* role (which is a Mobile role) allows management of Sync Gateway databases; and of Sync Gateway users and roles; and allows access to Sync Gateway's `/metrics` endpoint. The role does not allow access to Couchbase Web Console; and does not allow reading of application data. For information on Sync Gateway users and roles, see http://docs.couchbase.com/sync-gateway/3.0/access-control-concepts.html[Access Control Concepts^]. @@ -1163,7 +1172,7 @@ For information on Sync Gateway users and roles, see http://docs.couchbase.com/s [#sync-gateway-app] == Sync Gateway Application -The *Sync Gateway Application* role (which is a _Mobile_ role) allows management of Sync Gateway users and roles; and allows application data to be read and written through Sync Gateway. +The *Sync Gateway Application* role (which is a Mobile role) allows management of Sync Gateway users and roles; and allows application data to be read and written through Sync Gateway. The role does not allow access to Couchbase Web Console. For information on Sync Gateway users and roles, see http://docs.couchbase.com/sync-gateway/3.0/access-control-concepts.html[Access Control Concepts^]. @@ -1201,7 +1210,7 @@ For information on Sync Gateway users and roles, see http://docs.couchbase.com/s [#sync-gateway-application-read-only] == Sync Gateway Application Read Only -The *Sync Gateway Application Read Only* role (which is a _Mobile_ role) allows reading of Sync Gateway users and roles; and allows application data to be read through Sync Gateway. +The *Sync Gateway Application Read Only* role (which is a Mobile role) allows reading of Sync Gateway users and roles; and allows application data to be read through Sync Gateway. The role does not allow access to Couchbase Web Console. For information on Sync Gateway users and roles, see http://docs.couchbase.com/sync-gateway/3.0/access-control-concepts.html[Access Control Concepts^]. @@ -1239,7 +1248,7 @@ For information on Sync Gateway users and roles, see http://docs.couchbase.com/s [#sync-gateway-replicator] == Sync Gateway Replicator -The *Sync Gateway Replicator* role (which is a _Mobile_ role) allows management of Sync Gateway replications. +The *Sync Gateway Replicator* role (which is a Mobile role) allows management of Sync Gateway replications. The role does not allow access to Couchbase Web Console. [#table_sync_gateway_replicator_role,cols="15,8,8,8,8",hrows=3] @@ -1270,7 +1279,7 @@ The role does not allow access to Couchbase Web Console. [#sync-gateway-dev-ops] == Sync Gateway Dev Ops -The *Sync Gateway Dev Ops* role (which is a _Mobile_ role) allows management of Sync Gateway node-level configuration; and allows access to Syn Gateway's `/metrics` endpoint, for Prometheus integration. +The *Sync Gateway Dev Ops* role (which is a Mobile role) allows management of Sync Gateway node-level configuration; and allows access to Syn Gateway's `/metrics` endpoint, for Prometheus integration. The role does not allow access to Couchbase Web Console. [#table_sync_gateway_dev_ops_role,cols="15,8,8,8,8",hrows=3] @@ -1307,8 +1316,8 @@ The role does not allow access to Couchbase Web Console. [#data-reader] == Data Reader -The *Data Reader* role (which is a _Data_ role) allows data to be read _per collection_, given corresponding specifications for _bucket_ and _scope_. -Note that the role does _not_ permit the running of {sqlpp} queries (such as SELECT) against data. +The *Data Reader* role (which is a Data role) allows data to be read per collection, given corresponding specifications for bucket and scope. +Note that the role does not permit the running of {sqlpp} queries (such as SELECT) against data. The role does not allow access to Couchbase Web Console: it is intended to support applications, rather than users. [#table_data_reader_role,cols="15,8,8,8,8",hrows=3] @@ -1351,7 +1360,7 @@ The role does not allow access to Couchbase Web Console: it is intended to suppo [#data-writer] == Data Writer -The *Data Writer* role (which is a _Data_ role) allows data to be written _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Data Writer* role (which is a Data role) allows data to be written per collection, given corresponding specifications for bucket and scope. The role does not allow access to Couchbase Web Console: it is intended to support applications, rather than users. [#table_data_writer_role,cols="15,8,8,8,8",hrows=3] @@ -1388,7 +1397,7 @@ The role does not allow access to Couchbase Web Console: it is intended to suppo [#data-dcp-reader] == Data DCP Reader -The *Data DCP Reader* role (which is a _Data_ role) allows DCP streams to be initiated _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Data DCP Reader* role (which is a Data role) allows DCP streams to be initiated per collection, given corresponding specifications for bucket and scope. The role does not allow access to Couchbase Web Console: it is intended to support applications, rather than users. The role does allow the reading of data. @@ -1438,11 +1447,11 @@ The role does allow the reading of data. [#data-backup-and-restore] == Data Backup & Restore -The *Data Backup & Restore* role (which is a _Data_ role) allows data to be backed up and restored, _per bucket_. +The *Data Backup & Restore* role (which is a Data role) allows data to be backed up and restored, per bucket. The role supports the reading of data. The role does not allow access to Couchbase Web Console: it is intended to support applications, rather than users. -The privileges represented in this table are, from left to right, _Read_, _Write_, _Execute_, _Manage_, _Select_, _Backup_, _Create_, _List_, and _Build_. +The privileges represented in this table are, from left to right, Read, Write, Execute, Manage, Select, Backup, Create, List, and Build. [#table_data_backup_role,cols="8,3,3,3,3,3,3,3,3,3",hrows=3] |=== @@ -1575,7 +1584,7 @@ The privileges represented in this table are, from left to right, _Read_, _Write [#data-monitor] == Data Monitor -The *Data Monitor* role (which is a _Data_ role) allows statistics to be read for a given _bucket_, _scope_, or _collection_. +The *Data Monitor* role (which is a Data role) allows statistics to be read for a given bucket, scope, or collection. It does not allow access to Couchbase Web Console, and does not permit the reading of data. This role is intended to support application-access, rather than user-access. @@ -1609,7 +1618,7 @@ In versions of Couchbase Server prior to 5.5, this role was referred to as *Data [#views-admin] == Views Admin -The *Views Admin* role (which is a _Views_ role) allows the management of views, _per bucket_. +The *Views Admin* role (which is a Views role) allows the management of views, per bucket. The role allows access to Couchbase Web Console. [#table_views_admin_role,cols="15,8,8,8,8",hrows=3] @@ -1670,7 +1679,7 @@ The role allows access to Couchbase Web Console. [#views-reader] == Views Reader -The *Views Reader* role (which is an _Administrative_ role) allows data to be read from views, _per bucket_. +The *Views Reader* role (which is an Administrative role) allows data to be read from views, per bucket. This role does not allow access to Couchbase Web Console, and is intended to support applications, rather than users. [#table_views_reader_role,cols="15,8,8,8,8",hrows=3] @@ -1707,7 +1716,7 @@ This role does not allow access to Couchbase Web Console, and is intended to sup [#query-select] == Query Select -The *Query Select* role (which is a _Query & Index_ role) allows the SELECT statement to be executed _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Query Select* role (which is a Query & Index role) allows the SELECT statement to be executed per collection, given corresponding specifications for bucket and scope. This role allows access to Couchbase Web Console; it also supports the reading of data, and of bucket settings. [#table_query_select_role,cols="15,8,8,8,8",hrows=3] @@ -1756,7 +1765,7 @@ This role allows access to Couchbase Web Console; it also supports the reading o [#query-update] == Query Update -The *Query Update* role (which is a _Query & Index_ role) allows the UPDATE statement to be executed _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Query Update* role (which is a Query & Index role) allows the UPDATE statement to be executed per collection, given corresponding specifications for bucket and scope. The role supports access to Couchbase Web Console, and allows the writing (but not the reading) of data. It allows the reading of bucket settings. @@ -1806,7 +1815,7 @@ It allows the reading of bucket settings. [#query-insert] == Query Insert -The *Query Insert* role (which is a _Query & Index_ role) allows the INSERT statement to be executed _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Query Insert* role (which is a Query & Index role) allows the INSERT statement to be executed per collection, given corresponding specifications for bucket and scope. The role supports access to Couchbase Web Console, and allows the writing (but not the reading) of data. It allows the reading of bucket settings. @@ -1856,7 +1865,7 @@ It allows the reading of bucket settings. [#query-delete] == Query Delete -The *Query Delete* role (which is a _Query & Index_ role) allows the DELETE statement to be executed _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Query Delete* role (which is a Query & Index role) allows the DELETE statement to be executed per collection, given corresponding specifications for bucket and scope. The role supports access to Couchbase Server Web Console, and allows the deletion of data. It allows the reading of bucket settings. @@ -1960,7 +1969,7 @@ Administrators' queries automatically have permission to perform sequential scan [#query-manage-index] == Query Manage Index -The *Query Manage Index* role (which is a _Query & Index_ role) allows indexes to be managed _per collection_, given corresponding specifications for _bucket_ and _scope_. +The *Query Manage Index* role (which is a Query & Index role) allows indexes to be managed per collection, given corresponding specifications for bucket and scope. The role allows access to Couchbase Web Console, but does not permit the reading of data. [#table_query_manage_index_role,cols="15,8,8,8,8",hrows=3] @@ -2015,7 +2024,7 @@ The role allows access to Couchbase Web Console, but does not permit the reading [#eventing-full-admin] == Eventing Full Admin -The *Eventing Full Admin* role (which is an _Eventing_ role) allows creation and management of eventing functions. +The *Eventing Full Admin* role (which is an Eventing role) allows creation and management of eventing functions. The role allows access to Couchbase Web Console. [#table_eventing_admin_role,cols="15,8,8,8,8",hrows=3] @@ -2064,7 +2073,7 @@ The role allows access to Couchbase Web Console. [#eventing-manage-functions] == Manage Scope Functions (Eventing) -The *Manage Scope Functions* role (which is an _Eventing_ role) allows eventing functions for a given scope to be managed. +The *Manage Scope Functions* role (which is an Eventing role) allows eventing functions for a given scope to be managed. The role allows access to Couchbase Web Console. [#table_eventing_manage_functions,cols="15,8,8,8,8",hrows=3] @@ -2103,7 +2112,7 @@ The role allows access to Couchbase Web Console. [#backup-full-admin] == Backup Full Admin -The *Backup Full Admin* role (which is a _Backup_ role) allows performance of backup-related tasks. +The *Backup Full Admin* role (which is a Backup role) allows performance of backup-related tasks. The role allows access to Couchbase Web Console. [#table_backup_admin_role,cols="15,8,8,8,8",hrows=3] @@ -2152,7 +2161,7 @@ The role allows access to Couchbase Web Console. [#search-admin] == Search Admin -The *Search Admin* role (which is a _Search_ role) allows management of all features of the Search Service, _per bucket_. +The *Search Admin* role (which is a Search role) allows management of all features of the Search Service, per bucket. The role allows access to Couchbase Web Console. In versions of Couchbase Server prior to 5.5, this role was referred to as *FTS Admin*. @@ -2209,7 +2218,7 @@ In versions of Couchbase Server prior to 5.5, this role was referred to as *FTS [#search-reader] == Search Reader -The role *Search Reader* (which is a _Search_ role) allows _Full Text Search_ indexes to be searched for _bucket_, _scope_, and _collection_. +The role *Search Reader* (which is a Search role) allows Full Text Search indexes to be searched for bucket, scope, and collection. The role allows access to Couchbase Web Console, and supports the reading of data. In versions of Couchbase Server prior to 5.5, this role was referred to as *FTS Searcher*. @@ -2254,7 +2263,7 @@ In versions of Couchbase Server prior to 5.5, this role was referred to as *FTS [#analytics-select] == Analytics Select -The *Analytics Select* role (which is an _Analytics_ role) allows the querying of datasets for _bucket_, _scope_. and _collection_. +The *Analytics Select* role (which is an Analytics role) allows the querying of datasets for bucket, scope. and collection. The role allows access to Couchbase Web Console, and permits the reading of some data. [#table_analytics_select_role,cols="15,8,8,8,8",hrows=3] @@ -2291,7 +2300,7 @@ The role allows access to Couchbase Web Console, and permits the reading of some [#analytics-manager] == Analytics Manager -The *Analytics Manager* role (which is an _Analytics_ role) allows the management and querying of datasets created _per bucket_; and the management of Analytics Service local links. +The *Analytics Manager* role (which is an Analytics role) allows the management and querying of datasets created per bucket; and the management of Analytics Service local links. The role allows access to Couchbase Web Console, and permits the reading of some data. [#table_analytics_manager_role,cols="15,8,8,8,8",hrows=3] From 0a8e878c76713b826883bb7105c950119ac2ec4e Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 3 May 2024 11:25:41 -0400 Subject: [PATCH 03/16] In-progress revisions to get task infio. Working on ways to better format the reference page. --- .../rest-api/pages/backup-get-task-info.adoc | 77 +++++++++++++++---- 1 file changed, 61 insertions(+), 16 deletions(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index 8ec21515da..841135e30e 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -1,5 +1,5 @@ = Get Information on Tasks -:description: The Backup Service REST API allows information to be retrieved on the task history of an active, imported, or archived repository. +:description: The Backup Service REST API lets you retrieve the task history of an active, imported, or archived repository. [abstract] {description} @@ -8,47 +8,89 @@ == HTTP Methods and URIs ---- -GET /cluster/self/repository/< "active" | "imported" | "archived" >//taskHistory +GET /api/v1/cluster/self/repository/{repo-status}/{repository-name}/taskHistory -GET /cluster/self/repository/< "active" | "imported" | "archived" >//taskHistory? +GET /api/v1/cluster/self/repository/{repo-status}/{repository-name}/taskHistory?{task-subset-specification} ---- +.Path Parameters +[cols="2,3,2"] +|=== +|Name | Description | Schema + +| `repo-status` +| The status of the backup repository. +a| Must be one of: + +* `active` +* `imported` +* `archived` + + +| `repository-name` +| The name of the repository +| String + +| `task-subset-specification` +| One or more query parameters filter that limits the tasks this method returns. +| <> + +|=== + + + [#description] == Description -The `GET /cluster/self/repository/active//taskHistory` http method and URI return an array containing the entire task history for the repository specified by the `repository-name` path-parameter. +This HTTP method and URI return an array containing the entire task history for the repository specified by the `repository-name` path-parameter. + +The `task-subset-specification` lets you select a subset of the tasks that you want the method to return. + -The `GET /cluster/self/repository/active//taskHistory?` http method and URI return an array containing the task history for a subset of the tasks performed for the repository specified by the `repository-name` path-parameter. -In each case, the `repository-name` can be that of an active, imported, or archived repository. [#curl-syntax] == Curl Syntax ---- -curl -X GET http://:8097/cluster/self\ -/repository/< "active" | "imported" | "archived" >/\ -/taskHistory --u : +curl -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ +/repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ +-u $USERNAME:$PASSWORD -curl -X GET http://:8097/cluster/self\ -/repository/< "active" | "imported" | "archived" >/\ -/taskHistory? --u : +curl -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ +/repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory\ +/?$TASK_SUBSET_SPECIFICATION +-u $USERNAME:$PASSWORD ---- -A subset of tasks to be returned is optionally determined by the `task-subset-specification`, whose syntax is as follows: +[[subset-spec]] +===Task Subset Specifications + +You can filter the list of tasks this method returns using the optional task subset specification query string. + ---- first=&limit=&taskName= ---- +.Task Subset Query String Parameters +[cols="2,3,2"] +|=== +|Name | Description | Value + +| `date` +! The earliest date to + +|=== + The `date` specified as the value of the query parameter `first` is the earliest date for which tasks are included. The integer specified as the value of the query parameter `limit` is the maximum number of tasks to be returned. The string provided as the value of the optional query parameter `taskName` is the name of the single task to be returned. -The `username` and `password` must identify an administrator with the Full Admin role. +== Required Permissions + +Full Admin or Read-Only Admin roles. [#responses] == Responses @@ -60,6 +102,9 @@ If an internal error prevents successful execution, `500 Internal Server Error` Failure to authenticate returns `401 Unauthorized`. An incorrectly specified URI returns `404 Object Not Found`. + + + [#example] == Example From 1cfbb1c43a4ca58f0613a9dc832a8ee6d0997fdb Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 6 May 2024 15:04:28 -0400 Subject: [PATCH 04/16] First full draft, after working out some ideas for formatting reference pages. --- .../rest-api/pages/backup-get-task-info.adoc | 226 ++++++++++++++---- 1 file changed, 181 insertions(+), 45 deletions(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index 841135e30e..e13ba9755d 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -33,11 +33,39 @@ a| Must be one of: | `task-subset-specification` | One or more query parameters filter that limits the tasks this method returns. -| <> +| <> |=== +[[subset-spec]] +=== Task Subset Parameter String + +You can filter the list of tasks this method returns using the optional task subset specification query string. +You can supply one or more of the following parameters: + +---- +first={date}&limit={count}&taskName={task-name} +---- + +.Task Subset Query String Parameters +[cols="2,3,2"] +|=== +|Name | Description | Value +| `date` +| Only returns tasks that started after the supplied date. +| A datetime string in https://www.rfc-editor.org/rfc/rfc3339[RFC-3339] format + +| `count` +| The number of most recent tasks to return. +| Integer + +| `task-name` +a| Only returns task whose names exactly matches `task-name` including case. +Use this option to filter when multiple tasks are writing to the same repository. +| String + +|=== [#description] == Description @@ -46,78 +74,69 @@ This HTTP method and URI return an array containing the entire task history for The `task-subset-specification` lets you select a subset of the tasks that you want the method to return. - - - [#curl-syntax] == Curl Syntax ---- curl -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ -/repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ --u $USERNAME:$PASSWORD - -curl -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ -/repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory\ -/?$TASK_SUBSET_SPECIFICATION --u $USERNAME:$PASSWORD + /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ + -u $USERNAME:$PASSWORD +curl -G -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ + /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory + [-d 'first=$DATE'] [-d 'limit=$COUNT'] [-d 'taskName=$TASK_NAME'] + -u $USERNAME:$PASSWORD ---- -[[subset-spec]] -===Task Subset Specifications - -You can filter the list of tasks this method returns using the optional task subset specification query string. +== Required Permissions +Full Admin, Backup Full Admin, or Read-Only Admin roles. ----- -first=&limit=&taskName= ----- +[#responses] +== Responses -.Task Subset Query String Parameters -[cols="2,3,2"] |=== -|Name | Description | Value - -| `date` -! The earliest date to +|Value | Description -|=== +| `200 OK` and JSON array containing the tasks +| Successful call. -The `date` specified as the value of the query parameter `first` is the earliest date for which tasks are included. -The integer specified as the value of the query parameter `limit` is the maximum number of tasks to be returned. -The string provided as the value of the optional query parameter `taskName` is the name of the single task to be returned. +| `400` +| Invalid parameter. -== Required Permissions +| `400 Object Not found` +| The repository in the endpoint URI does not exist. -Full Admin or Read-Only Admin roles. +| `401 Unauthorized` +| Authorization failure due to incorrect username or password. -[#responses] -== Responses +| `403 Forbidden`, plus a JSON message explaining the minimum permissions. +| The provided username has insufficient privileges to call this method. -Successful execution returns `200 OK`, and an array each of whose members is an object containing information on a task discharged for the repository. -If an invalid parameter is specified, `400` is returned. -If the specified repository cannot be found, `404 Object Not Found` is returned. -If an internal error prevents successful execution, `500 Internal Server Error` is returned. -Failure to authenticate returns `401 Unauthorized`. -An incorrectly specified URI returns `404 Object Not Found`. +| `404 Object Not Found` +| Error in the URI path. +| `500 Internal Server Error` +| Error in Couchbase Server. +|=== [#example] -== Example +== Examples The following call returns the entire task history for the active repository `quarterHourBackups`: +[source, console] ---- curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self/\ -repository/active/quarterHourBackups/taskHistory \ --u Administrator:password + repository/active/quarterHourBackups/taskHistory \ + -u Administrator:password ---- If the call is successful, the first part of the potentially extensive output may appear as follows: +[source, json] ---- [ { @@ -179,12 +198,129 @@ If the call is successful, the first part of the potentially extensive output ma . ---- -The array thus includes objects for specific runs of the task `fifteenMinuteBackup`. +The array includes objects for specific runs of the task `fifteenMinuteBackup`. Each object incudes the `start` and `end` time of the task; and lists specific `node_runs`, with details on buckets whose data was backed up. +The following example demonstrates using the `first` and `limit` query parameters to limit the results to two tasks that started after + +[source, console] +---- +curl -G -s -X GET http://127.0.0.1:8097/api/v1/cluster/self/repository/active/quarterHourBackups/taskHistory \ + -d 'first=2024-05-06T14:24:22Z' + -d 'limit=2' + -u Administrator:password | jq +---- + +A successful call returns a task list resembling the following: + +[source, json] +---- +[ + { + "task_name": "fifteenMinuteBackup", + "status": "done", + "start": "2024-05-06T17:24:22.471826882Z", + "end": "2024-05-06T17:24:28.901488385Z", + "node_runs": [ + { + "node_id": "1a41682a59f40d3932d2cf7b131a2312", + "status": "done", + "start": "2024-05-06T17:24:22.483698673Z", + "end": "2024-05-06T17:24:28.889650843Z", + "progress": 100, + "stats": { + "id": "36dfeb46-78b0-428a-b9d6-36b0169ac685", + "current_transfer": 1, + "total_transfers": 1, + "transfers": [ + { + "description": "Backing up to 2024-05-06T17_24_22.886394673Z", + "stats": { + "started_at": 1715016262871131000, + "finished_at": 1715016268874403800, + "buckets": { + "travel-sample": { + "total_items": 63344, + "total_vbuckets": 1024, + "vbuckets_complete": 1024, + "bytes_received": 28672, + "failover_logs_received": 1024, + "started_at": 1715016266774038500, + "finished_at": 1715016268870321400, + "complete": true + } + }, + "users": {}, + "complete": true + }, + "progress": 100, + "eta": "2024-05-06T17:24:28.878288801Z" + } + ], + "progress": 100, + "eta": "2024-05-06T17:24:28.878288801Z" + }, + "error_code": 0 + } + ], + "error_code": 0, + "type": "BACKUP" + }, + { + "task_name": "fifteenMinuteBackup", + "status": "done", + "start": "2024-05-06T17:09:22.279129423Z", + "end": "2024-05-06T17:09:28.677706343Z", + "node_runs": [ + { + "node_id": "1a41682a59f40d3932d2cf7b131a2312", + "status": "done", + "start": "2024-05-06T17:09:22.291632632Z", + "end": "2024-05-06T17:09:28.667370885Z", + "progress": 100, + "stats": { + "id": "7dabe789-0413-4ef2-b7d9-e942cab1da75", + "current_transfer": 1, + "total_transfers": 1, + "transfers": [ + { + "description": "Backing up to 2024-05-06T17_09_22.690112298Z", + "stats": { + "started_at": 1715015362678973000, + "finished_at": 1715015368655166200, + "buckets": { + "travel-sample": { + "total_items": 63344, + "total_vbuckets": 1024, + "vbuckets_complete": 1024, + "bytes_received": 28672, + "failover_logs_received": 1024, + "started_at": 1715015366548654800, + "finished_at": 1715015368651093200, + "complete": true + } + }, + "users": {}, + "complete": true + }, + "progress": 100, + "eta": "2024-05-06T17:09:28.658444968Z" + } + ], + "progress": 100, + "eta": "2024-05-06T17:09:28.658444968Z" + }, + "error_code": 0 + } + ], + "error_code": 0, + "type": "BACKUP" + } +] +---- [#see-also] == See Also -An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. -Information on using the Backup Service REST API to create a plan (and in so doing, define one or more tasks) is provided in xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. +* For a an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. +* For a step-by-step guide to configure and use the Backup Service using the Souchbase Server Web Console, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* For information about using the Backup Service REST API to create a plan, see xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. From 0ad2e9a85ae2cc045b2d601325bcc6f88491b483 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 7 May 2024 10:14:05 -0400 Subject: [PATCH 05/16] Updated based on the new placeholder standards. Some other minor fixups. --- .../rest-api/pages/backup-get-task-info.adoc | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index e13ba9755d..388006fdcd 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -1,16 +1,20 @@ = Get Information on Tasks :description: The Backup Service REST API lets you retrieve the task history of an active, imported, or archived repository. +[#description] +== Description [abstract] -{description} +This HTTP method and URI return an array containing the entire task history for the repository specified by the `REPO_NAME` path-parameter. + +The optional `TASK_SUBSET_PARAMETERS` let you select a subset of the tasks that you want the method to return. [#http-methods-and-uris] == HTTP Methods and URIs ---- -GET /api/v1/cluster/self/repository/{repo-status}/{repository-name}/taskHistory +GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME}/taskHistory -GET /api/v1/cluster/self/repository/{repo-status}/{repository-name}/taskHistory?{task-subset-specification} +GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME}/taskHistory?{TASK_SUBSET_PARAMETERS} ---- .Path Parameters @@ -18,7 +22,7 @@ GET /api/v1/cluster/self/repository/{repo-status}/{repository-name}/taskHistory? |=== |Name | Description | Schema -| `repo-status` +| `REPO_STATUS` | The status of the backup repository. a| Must be one of: @@ -27,12 +31,12 @@ a| Must be one of: * `archived` -| `repository-name` +| `REPO_NAME` | The name of the repository | String -| `task-subset-specification` -| One or more query parameters filter that limits the tasks this method returns. +| `TASK_SUBSET_PARAMETERS` +| One or more optional query parameters that filter the list of tasks this method returns. | <> |=== @@ -44,7 +48,7 @@ You can filter the list of tasks this method returns using the optional task sub You can supply one or more of the following parameters: ---- -first={date}&limit={count}&taskName={task-name} +first={DATE}&limit={COUNT}&taskName={TASK_NAME} ---- .Task Subset Query String Parameters @@ -52,28 +56,21 @@ first={date}&limit={count}&taskName={task-name} |=== |Name | Description | Value -| `date` +| `DATE` | Only returns tasks that started after the supplied date. | A datetime string in https://www.rfc-editor.org/rfc/rfc3339[RFC-3339] format -| `count` +| `COUNT` | The number of most recent tasks to return. | Integer -| `task-name` -a| Only returns task whose names exactly matches `task-name` including case. +| `TASK_NAME` +a| Only returns tasks whose name exactly matches `TASK_NAME` including case. Use this option to filter when multiple tasks are writing to the same repository. | String |=== -[#description] -== Description - -This HTTP method and URI return an array containing the entire task history for the repository specified by the `repository-name` path-parameter. - -The `task-subset-specification` lets you select a subset of the tasks that you want the method to return. - [#curl-syntax] == Curl Syntax @@ -121,10 +118,11 @@ Full Admin, Backup Full Admin, or Read-Only Admin roles. |=== - [#example] == Examples +NOTE: The following examples assume you are running the curl command from a node that is running the Backup Service. + The following call returns the entire task history for the active repository `quarterHourBackups`: [source, console] @@ -196,12 +194,14 @@ If the call is successful, the first part of the potentially extensive output ma . . . + } +] ---- The array includes objects for specific runs of the task `fifteenMinuteBackup`. Each object incudes the `start` and `end` time of the task; and lists specific `node_runs`, with details on buckets whose data was backed up. -The following example demonstrates using the `first` and `limit` query parameters to limit the results to two tasks that started after +The following example demonstrates using the `first` and `limit` query parameters to limit the results to two tasks that started after 14:24:22 on May 5th, 2024 GMT. [source, console] ---- @@ -322,5 +322,5 @@ A successful call returns a task list resembling the following: == See Also * For a an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -* For a step-by-step guide to configure and use the Backup Service using the Souchbase Server Web Console, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* For a step-by-step guide to configure and use the Backup Service using the Couchbase Server Web Console, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. * For information about using the Backup Service REST API to create a plan, see xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. From 02b4487a30c6a16b4e4a09a1f7ea90dda1cfc379 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 7 May 2024 10:23:32 -0400 Subject: [PATCH 06/16] Emphasized we need ot use the backup service port. --- modules/rest-api/pages/backup-get-task-info.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index 388006fdcd..7de5a00740 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -75,11 +75,11 @@ Use this option to filter when multiple tasks are writing to the same repositor == Curl Syntax ---- -curl -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ +curl -X GET http://$NODE_ADDRESS:$BACKUP_SERVICE_PORT/cluster/self\ /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ -u $USERNAME:$PASSWORD -curl -G -X GET http://$NODE_ADDRESS:$PORT/cluster/self\ +curl -G -X GET http://$NODE_ADDRESS:$BACKUP_SERVICE_PORT/cluster/self\ /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory [-d 'first=$DATE'] [-d 'limit=$COUNT'] [-d 'taskName=$TASK_NAME'] -u $USERNAME:$PASSWORD From 214c6f9866ef75f0bce803ba5b29e136d45b18de Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 7 May 2024 10:25:12 -0400 Subject: [PATCH 07/16] Changed title to be more explicite and get rid of the "information on" Vale nag. --- modules/rest-api/pages/backup-get-task-info.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index 7de5a00740..e40bc9344c 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -1,4 +1,4 @@ -= Get Information on Tasks += Get Backup Task History :description: The Backup Service REST API lets you retrieve the task history of an active, imported, or archived repository. [#description] From 72d5082b592fb11923a5b56df64d14b511ac0fca Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 7 May 2024 10:27:32 -0400 Subject: [PATCH 08/16] Updated topic name in links --- modules/ROOT/nav.adoc | 2 +- modules/rest-api/pages/backup-pause-and-resume-tasks.adoc | 2 +- modules/rest-api/partials/rest-backup-service-table.adoc | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 91e9d3b64c..598582567a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -664,7 +664,7 @@ include::cli:partial$cbcli/nav.adoc[] *** xref:rest-api:backup-create-repository.adoc[Create a Repository] *** xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories] *** xref:rest-api:backup-get-plan-info.adoc[Get Information on Plans] - *** xref:rest-api:backup-get-task-info.adoc[Get Information on Tasks] + *** xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] *** xref:rest-api:backup-pause-and-resume-tasks.adoc[Pause and Resume Tasks] *** xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data] *** xref:rest-api:backup-trigger-backup.adoc[Perform an Immediate Backup] diff --git a/modules/rest-api/pages/backup-pause-and-resume-tasks.adoc b/modules/rest-api/pages/backup-pause-and-resume-tasks.adoc index b180313bb0..339783b33f 100644 --- a/modules/rest-api/pages/backup-pause-and-resume-tasks.adoc +++ b/modules/rest-api/pages/backup-pause-and-resume-tasks.adoc @@ -73,4 +73,4 @@ Again, success returns `200 OK`. An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. Information on using the Backup Service REST API to create a plan (and in so doing, define one or more tasks) is provided in xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. -To get information on currently defined tasks, see xref:rest-api:backup-get-task-info.adoc[Get Information on Tasks]. +To get information on currently defined tasks, see xref:rest-api:backup-get-task-info.adoc[Get Backup Task History]. diff --git a/modules/rest-api/partials/rest-backup-service-table.adoc b/modules/rest-api/partials/rest-backup-service-table.adoc index 29f9e4758f..9640b3d49c 100644 --- a/modules/rest-api/partials/rest-backup-service-table.adoc +++ b/modules/rest-api/partials/rest-backup-service-table.adoc @@ -132,11 +132,11 @@ | `GET` | `/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory` -| xref:rest-api:backup-get-task-info.adoc[Get Information on Tasks] +| xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] | `GET` | `/cluster/self/repository/<'active'|'archived'|'imported'>//taskHistory?` -| xref:rest-api:backup-get-task-info.adoc[Get Information on Tasks] +| xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] |=== From c6ced66cdc27edba04d6a6810edd6794f0b186ea Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 09:10:02 -0400 Subject: [PATCH 09/16] Updated and reformatted several other impacted reference pages. --- modules/ROOT/nav.adoc | 2 +- .../partials/new-features-76_2.adoc | 2 +- .../pages/backup-archive-a-repository.adoc | 4 +- .../rest-api/pages/backup-get-plan-info.adoc | 83 +++++++++--- .../pages/backup-get-repository-info.adoc | 123 +++++++++++++----- .../rest-api/pages/backup-get-task-info.adoc | 5 +- .../partials/rest-backup-service-table.adoc | 6 +- 7 files changed, 161 insertions(+), 64 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 598582567a..313b4e8774 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -662,7 +662,7 @@ include::cli:partial$cbcli/nav.adoc[] ** xref:rest-api:backup-rest-api.adoc[Backup Service API] *** xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans] *** xref:rest-api:backup-create-repository.adoc[Create a Repository] - *** xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories] + *** xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] *** xref:rest-api:backup-get-plan-info.adoc[Get Information on Plans] *** xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] *** xref:rest-api:backup-pause-and-resume-tasks.adoc[Pause and Resume Tasks] diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index 853bff2d62..806737c1d7 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -2,7 +2,7 @@ * Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: -** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active`] +** xref:rest-api:backup-get-repository-info.adoc[`/cluster/self/repository/active`] ** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active/JOB-NAME/taskHistory`] ** xref:rest-api:backup-get-plan-info.adoc[`/plan/PLAN-NAME`] diff --git a/modules/rest-api/pages/backup-archive-a-repository.adoc b/modules/rest-api/pages/backup-archive-a-repository.adoc index 4ddb2acc13..09fcf92fe3 100644 --- a/modules/rest-api/pages/backup-archive-a-repository.adoc +++ b/modules/rest-api/pages/backup-archive-a-repository.adoc @@ -16,7 +16,7 @@ POST /repository/active//archive Archives the specified repository. This means that no further scheduled or manually triggered tasks can be run on the repository; with the exception of those that _retrieve information_, _restore data_, and _examine data_. -(See xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories], xref:rest-api:backup-restore-data.adoc[Restore Data], and xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data], respectively.) +(See xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information], xref:rest-api:backup-restore-data.adoc[Restore Data], and xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data], respectively.) Note that a repository that has been archived _cannot_ be returned to active state. @@ -74,6 +74,6 @@ Successful execution returns `200 OK`. An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. -Information on getting information from an archived repository is provided in xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories]. +Information on getting information from an archived repository is provided in xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information]. Information on restoring data from an archived repository is provided in xref:rest-api:backup-restore-data.adoc[Restore Data]. Information on examining data within an archived repository is provided in xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data]. diff --git a/modules/rest-api/pages/backup-get-plan-info.adoc b/modules/rest-api/pages/backup-get-plan-info.adoc index 3023fa8909..d960b85c4b 100644 --- a/modules/rest-api/pages/backup-get-plan-info.adoc +++ b/modules/rest-api/pages/backup-get-plan-info.adoc @@ -7,47 +7,80 @@ [#http-methods-and-uris] == HTTP Methods and URIs +Get a list of all defined backup plans: + ---- GET /plan +---- + +Get detailed information about a specific backup plan: -GET /plan/ ---- +GET /plan/{PLAN_NAME} +---- + +.Path Parameters +[cols="2,3,2"] +|=== +|Name | Description | Schema -[#description] -== Description +| `PLAN_NAME` +| The name of a plan. +| String -The `GET /plan` http method and URI return an array of plans, currently defined for the cluster. -The `GET /plan/` http method and URI return information on a single, specified plan. +|=== [#curl-syntax] == Curl Syntax ---- -curl -X GET http://:8097/plan - -u : +curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/plan + -u $USERNAME:$PASSWORD -curl -X GET http://:8097/plan/ - -u : +curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT:8097/plan/$PLAN_NAME + -u $USERNAME:$PASSWORD ---- -The `` must be the name of a plan currently defined for the cluster. -The `username` and `password` must identify an administrator with the Full Admin role. +== Required Permissions + +Full Admin, Backup Full Admin, or Read-Only Admin roles. + + [#responses] == Responses -If a specified `plan-id` does not exist, `404 Object Not Found` is returned, with an object such as the following: `{"status":404,"msg":"requested plan not found"}`. -Failure to authenticate returns `401 Unauthorized`. -An incorrectly specified URI returns `404 Object Not Found`. +|=== +|Value | Description + +| `200 OK` and JSON array containing plan information depending on the specific endpoint. +| Successful call. +| `400` +| Invalid parameter. + +| `401 Unauthorized` +| Authorization failure due to incorrect username or password. + +| `403 Forbidden`, plus a JSON message explaining the minimum permissions. +| The provided username has insufficient privileges to call this method. + +| `404 Object Not found` and the message `{"status":404,"msg":"requested plan not found"}` +| The plan in the endpoint URI does not exist. + +| `500 Could not retrieve the requested repository` +| Error in Couchbase Server. + +|=== [#examples] == Examples -The following call returns an array, each of whose members is an object containing information for a plan currently defined for the cluster. -Note that the output is piped to the https://stedolan.github.io/jq[jq^] command, to facilitate readability: +The following call returns an array each of whose members is an object containing information for a plan currently defined for the cluster. +The command pipes the output to the https://stedolan.github.io/jq[`jq`^] command to improve readability: +[source, console] ---- curl -v -X GET http://127.0.0.1:8097/api/v1/api/v1/plan \ -u Administrator:password | jq '.' @@ -55,6 +88,8 @@ curl -v -X GET http://127.0.0.1:8097/api/v1/api/v1/plan \ If the call is successful, `200 OK` is returned, with an array the initial part of which may appear as follows: + +[source, json] ---- [ { @@ -101,6 +136,10 @@ If the call is successful, `200 OK` is returned, with an array the initial part . . . + } + ] + } +] ---- Each object in the array contains information on the specified plan. @@ -109,6 +148,7 @@ Each task is listed with an account of its type and schedule. The following call returns information specifically on the plan `testPlan2`: +[source, console] ---- curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/plan/testPlan2 \ -u Administrator:password | jq '.' @@ -116,6 +156,7 @@ curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/plan/testPlan2 \ If the call is successful, `200 OK` is returned, with the following object: +[source, json] ---- { "name": "testPlan2", @@ -150,7 +191,7 @@ If the call is successful, `200 OK` is returned, with the following object: } ---- -The object contains information on the specified plan. +The object contains information about the specified plan. The information includes confirmation of the services for which data is backed up by the plan; and the tasks that are performed for the plan. Each task is listed with an account of its type and schedule. @@ -158,7 +199,7 @@ Each task is listed with an account of its type and schedule. [#see-also] == See Also -An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. -For information on using the Backup Service REST API to create and edit plans, see xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. -For information on deleting plans, see xref:rest-api:backup-delete-plan.adoc[Delete a Plan]. +* For an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[]. +* For a step-by-step guide to using Couchbase Server Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[]. +* For Information about using the Backup Service REST API to create a plan, see xref:rest-api:backup-create-and-edit-plans.adoc[]. +* For information about deleting plans, see xref:rest-api:backup-delete-plan.adoc[]. diff --git a/modules/rest-api/pages/backup-get-repository-info.adoc b/modules/rest-api/pages/backup-get-repository-info.adoc index 4d3b5f94a1..525e69915f 100644 --- a/modules/rest-api/pages/backup-get-repository-info.adoc +++ b/modules/rest-api/pages/backup-get-repository-info.adoc @@ -1,71 +1,114 @@ -= Get Information on Repositories -:description: The Backup Service REST API allows information to be retrieved on active, imported, or archived repositories. += Get Backup Repository Information +:description: The Backup Service REST API lets you list and get information about the active, imported, and archived backup repositories. [abstract] + +== Description + {description} [#http-methods-and-uris] == HTTP Methods and URIs + +List all backup repositories with a specific status: +---- +GET /api/v1/cluster/self/repository/{REPO_STATUS} ---- -GET /cluster/self/repository/< "active" | "imported" | "archived" > -GET /cluster/self/repository/< "active" | "imported" | "archived" >/ -GET /cluster/self/repository/< "active" | "imported" | "archived" >//info +Get overview information about a specific backup repository: +---- +GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME} ---- -[#description] -== Description -The `GET /cluster/self/repository/< "active" | "imported" | "archived" >` http method and URI return an array, each of whose members is an object containing information on a repository. -Information includes repository names, file or cluster paths, and plan details. +Get detailed information about a specific backup repository including backup names and dates, buckets, items, and mutations: +---- +GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME}/info +---- -The `GET /cluster/self/repository/< "active" | "imported" | "archived" >/` http method and URI return a single object, containing information on the repository whose name is specified by the `repository-id` path-parameter. -Information includes repository names, file or cluster paths, and plan details. +NOTE: These URIs are only available from the Backup Service port (8097 by default) on nodes running the Backup Service. + +.Path Parameters +[cols="2,3,2"] +|=== +|Name | Description | Schema + +|`REPO_STATUS` +| The current status of the repository. +a| One of the following: + +* `active` +* `imported` +* `archived` -The `GET /cluster/self/repository/< "active" | "imported" | "archived" >//info` http method and URI return a single object, containing information on the repository whose name is specified by the `repository-id` path-parameter. -Information includes backup names and dates, buckets, items, and mutations. +| `REPO_NAME` +| The name of the backup repository +| String + +|=== [#curl-syntax] == Curl Syntax ---- -curl -X GET :8097/cluster/self/\ -repository/< "active" | "imported" | "archived" > --u : +curl -X GET $BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/cluster/self/\ +repository/$REPO_STATUS +-u $USERNAME:$PASSWORD curl -X GET :8097/cluster/self/\ -repository/< "active" | "imported" | "archived" >/ --u : +repository/$REPO_STATUS/$REPO_NAME +-u $USERNAME:$PASSWORD curl -X GET :8097/cluster/self/\ -repository/< "active" | "imported" | "archived" >//info --u : +repository/$REPO_STATUS/$REPO_NAME/info +-u $USERNAME:$PASSWORD ---- -The `repository-id` path-parameter must be the name of a repository. -The `username` and `password` must identify an administrator with the Full Admin role. + +== Required Permissions + +Full Admin, Backup Full Admin, or Read-Only Admin roles. + [#responses] == Responses -Successful location of all repositories returns `200 OK`, and an array of repositories. +|=== +|Value | Description + +| `200 OK` and JSON array containing repository information depending on the specific endpoint. +| Successful call. + +| `400` +| Invalid parameter. -Successful location of a specified repository returns `200 OK` and an object containing information on the repository. -If the specified repository is not located, `404` is returned, with the following object: `{"status": 404, "msg": "no repositories found"}`. +| `400 Object Not found` +| The repository in the endpoint URI does not exist. + +| `401 Unauthorized` +| Authorization failure due to incorrect username or password. + +| `403 Forbidden`, plus a JSON message explaining the minimum permissions. +| The provided username has insufficient privileges to call this method. + +| `404 Object Not Found` +| Error in the URI path. + +| `500 Could not retrieve the requested repository` +| Error in Couchbase Server. + +|=== -If an internal error causes the call the fail, `500` is returned; with the message `Could not retrieve the requested repository`. -Failure to authenticate returns `401 Unauthorized`. -An incorrectly specified URI returns `404 Object Not Found`. -An incorrectly specified method returns `404 Object Not Found`, and returns the object `{"status":404,"msg":"requested plan not found"}`. [#examples] == Examples -The following call returns information on all currently defined, active repositories,. -Note that the output is piped to the https://stedolan.github.io/jq/[jq^] command, to facilitate readability. +The following `curl` command returns information about all active repositories. +The command pipes the output to the https://stedolan.github.io/jq/[`jq`^] command for readability. +[source, console] ---- curl -v -X GET \ http://127.0.0.1:8097/api/v1/cluster/self/repository/active \ @@ -76,6 +119,7 @@ Successful execution returns a JSON array, each of whose members is an object co Information includes repository names, file or cluster paths, and plan details. The initial part of the potentially extensive output might appear as follows: +[source, json] ---- [ { @@ -113,6 +157,8 @@ The initial part of the potentially extensive output might appear as follows: . . . + } +] ---- Each object thus contains the `id` (name), `plan_name`, `state`, `repo` (unique identifier), and scheduled tasks for the repository. @@ -120,6 +166,7 @@ It also contains an account of the repository's health, its creation time, and t The following call returns information on a specific, named, active repository: +[source, console] ---- curl -v -X GET \ http://127.0.0.1:8091/_p/backup/api/v1/cluster/self/repository/active/restRepo \ @@ -128,6 +175,7 @@ http://127.0.0.1:8091/_p/backup/api/v1/cluster/self/repository/active/restRepo \ If successful, the call returns the following object: +[source, json] ---- { "id": "restRepo", @@ -169,6 +217,7 @@ The object thus contains information on the specified repository. The following call returns information including backup names and dates, buckets, items, and mutations; on an imported repository named `mergedRepo`: +[source, console] ---- curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self/repository/imported/mergedRepo/info \ -u Administrator:password | jq @@ -176,6 +225,7 @@ curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self/repository/imported/mer If successful, the initial part of the potentially extensive output is as follows: +[source, json] ---- { "name": "7509894b-7138-40fe-917e-9581d298482c", @@ -252,13 +302,16 @@ If successful, the initial part of the potentially extensive output is as follow . . . + } + ] +} ---- [#see-also] == See Also -An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. -Information on using the Backup Service REST API to create a plan is provided in xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. -Information on using the Backup Service REST API to create a repository is provided in xref:rest-api:backup-create-repository.adoc[Create a Repository]. +* For an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. +* For a step-by-step guide to using Couchbase Server Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* For Information about using the Backup Service REST API to create a plan, see xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans]. +* For information about using the Backup Service REST API to create a repository, see xref:rest-api:backup-create-repository.adoc[Create a Repository]. diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index e40bc9344c..3729cfba63 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -17,6 +17,8 @@ GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME}/taskHistory GET /api/v1/cluster/self/repository/{REPO_STATUS}/{REPO_NAME}/taskHistory?{TASK_SUBSET_PARAMETERS} ---- +NOTE: These URIs are only available from the Backup Service port (8097 by default) on nodes running the Backup Service. + .Path Parameters [cols="2,3,2"] |=== @@ -75,7 +77,7 @@ Use this option to filter when multiple tasks are writing to the same repositor == Curl Syntax ---- -curl -X GET http://$NODE_ADDRESS:$BACKUP_SERVICE_PORT/cluster/self\ +curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/cluster/self\ /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ -u $USERNAME:$PASSWORD @@ -318,6 +320,7 @@ A successful call returns a task list resembling the following: } ] ---- + [#see-also] == See Also diff --git a/modules/rest-api/partials/rest-backup-service-table.adoc b/modules/rest-api/partials/rest-backup-service-table.adoc index 9640b3d49c..ec26f636cb 100644 --- a/modules/rest-api/partials/rest-backup-service-table.adoc +++ b/modules/rest-api/partials/rest-backup-service-table.adoc @@ -37,15 +37,15 @@ | `GET` | `/cluster/self/repository/<'active'|'archived'|'imported'>` -| xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories] +| xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `GET` | `/cluster/self/repository/active/` -| xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories] +| xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `GET` | `/cluster/self/repository/<'active'|'archived'|'imported'>//info` -| xref:rest-api:backup-get-repository-info.adoc[Get Information on Repositories] +| xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] | `POST` | `/cluster/self/repository/active/` From 692398c685146b92ac07e6ad76fbda478ce8b195 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 09:37:58 -0400 Subject: [PATCH 10/16] Renamed topic --- modules/ROOT/nav.adoc | 2 +- modules/rest-api/pages/backup-get-plan-info.adoc | 2 +- modules/rest-api/partials/rest-backup-service-table.adoc | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 313b4e8774..0fc495c86e 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -663,7 +663,7 @@ include::cli:partial$cbcli/nav.adoc[] *** xref:rest-api:backup-create-and-edit-plans.adoc[Create and Edit Plans] *** xref:rest-api:backup-create-repository.adoc[Create a Repository] *** xref:rest-api:backup-get-repository-info.adoc[Get Backup Repository Information] - *** xref:rest-api:backup-get-plan-info.adoc[Get Information on Plans] + *** xref:rest-api:backup-get-plan-info.adoc[Get Backup Plan Information] *** xref:rest-api:backup-get-task-info.adoc[Get Backup Task History] *** xref:rest-api:backup-pause-and-resume-tasks.adoc[Pause and Resume Tasks] *** xref:rest-api:backup-examine-data.adoc[Examine Backed-Up Data] diff --git a/modules/rest-api/pages/backup-get-plan-info.adoc b/modules/rest-api/pages/backup-get-plan-info.adoc index d960b85c4b..77520fcda6 100644 --- a/modules/rest-api/pages/backup-get-plan-info.adoc +++ b/modules/rest-api/pages/backup-get-plan-info.adoc @@ -1,4 +1,4 @@ -= Get Information on Plans += Get Backup Plan Information :description: The Backup Service REST API allows information on plans to be retrieved. [abstract] diff --git a/modules/rest-api/partials/rest-backup-service-table.adoc b/modules/rest-api/partials/rest-backup-service-table.adoc index ec26f636cb..f31161b9cd 100644 --- a/modules/rest-api/partials/rest-backup-service-table.adoc +++ b/modules/rest-api/partials/rest-backup-service-table.adoc @@ -104,11 +104,11 @@ | `GET` | `/cluster/plan` -| xref:rest-api:backup-get-plan-info.adoc[Get Information on Plans] +| xref:rest-api:backup-get-plan-info.adoc[Get Backup Plan Information] | `GET` | `/cluster/plan/` -| xref:rest-api:backup-get-plan-info.adoc[Get Information on Plans] +| xref:rest-api:backup-get-plan-info.adoc[Get Backup Plan Information] | `POST` | `/cluster/plan/` From d6b7d445813b610f728809d927fa0b58b05b6f25 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 09:53:48 -0400 Subject: [PATCH 11/16] Made description non-passive. --- modules/rest-api/pages/backup-get-plan-info.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/rest-api/pages/backup-get-plan-info.adoc b/modules/rest-api/pages/backup-get-plan-info.adoc index 77520fcda6..c7e07d775d 100644 --- a/modules/rest-api/pages/backup-get-plan-info.adoc +++ b/modules/rest-api/pages/backup-get-plan-info.adoc @@ -1,5 +1,5 @@ = Get Backup Plan Information -:description: The Backup Service REST API allows information on plans to be retrieved. +:description: The Backup Service REST API lets you get information about backup plans. [abstract] {description} @@ -25,7 +25,7 @@ GET /plan/{PLAN_NAME} |Name | Description | Schema | `PLAN_NAME` -| The name of a plan. +| The name of a backup plan. | String |=== From 1911bf5cd73e4074f7056824028ecf0a4aeb6b27 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 10:43:08 -0400 Subject: [PATCH 12/16] Fixed placeholder text --- modules/rest-api/pages/backup-get-task-info.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/rest-api/pages/backup-get-task-info.adoc b/modules/rest-api/pages/backup-get-task-info.adoc index 3729cfba63..5fffba9907 100644 --- a/modules/rest-api/pages/backup-get-task-info.adoc +++ b/modules/rest-api/pages/backup-get-task-info.adoc @@ -81,7 +81,7 @@ curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/cluster/self\ /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory \ -u $USERNAME:$PASSWORD -curl -G -X GET http://$NODE_ADDRESS:$BACKUP_SERVICE_PORT/cluster/self\ +curl -G -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/cluster/self\ /repository/$REPO_STATUS/$REPOSITORY_NAME/taskHistory [-d 'first=$DATE'] [-d 'limit=$COUNT'] [-d 'taskName=$TASK_NAME'] -u $USERNAME:$PASSWORD From 0d2ee21d9be2c7eda45d776665237093e2b8fe38 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 10:57:34 -0400 Subject: [PATCH 13/16] Fixing anchors --- modules/introduction/pages/whats-new.adoc | 2 +- modules/introduction/partials/new-features-76_2.adoc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/introduction/pages/whats-new.adoc b/modules/introduction/pages/whats-new.adoc index 4802aef775..14da19e71b 100644 --- a/modules/introduction/pages/whats-new.adoc +++ b/modules/introduction/pages/whats-new.adoc @@ -8,7 +8,7 @@ For information about platform support changes, deprecation notifications, notable improvements, and fixed and known issues, refer to the xref:release-notes:relnotes.adoc[Release Notes]. -[#new-features-7.6.2] +[#new-features-762] == New Features and Enhancements in 7.6.2 The following new features are provided in this release. diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index 806737c1d7..6984f445a5 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -1,3 +1,4 @@ +[backup_762] === Backup * Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: From 1c0abcfb30f5cd4d31f8ceca9f6765d0ff0a145d Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Wed, 8 May 2024 11:18:40 -0400 Subject: [PATCH 14/16] Fixing anchors again --- modules/introduction/partials/new-features-76_2.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index 6984f445a5..9b81d9b177 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -1,4 +1,4 @@ -[backup_762] +[#backup_762] === Backup * Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: @@ -6,5 +6,3 @@ ** xref:rest-api:backup-get-repository-info.adoc[`/cluster/self/repository/active`] ** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active/JOB-NAME/taskHistory`] ** xref:rest-api:backup-get-plan-info.adoc[`/plan/PLAN-NAME`] - - From 7a411859e7db5092e07e3355c7240f6c228f1ef7 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Thu, 9 May 2024 15:44:12 -0400 Subject: [PATCH 15/16] Heavy rewrite of backup-manager-config: * Fixed completely wrong examples that had the wrong URI and/or wrong port. * Hid/removed the history_rotation_period setting which seems to have been silently removed from the product. Setting it had no effect. Only evidence I could find for its removal were some references to "dead code" in github. * Changed references to "rotating config files" to rotating history files. * Removed PUT method because it doesn't seem to work. * Updated formatting/wording to meet standards. --- .../pages/backup-get-cluster-info.adoc | 26 +++-- .../rest-api/pages/backup-manage-config.adoc | 98 ++++++++++--------- 2 files changed, 72 insertions(+), 52 deletions(-) diff --git a/modules/rest-api/pages/backup-get-cluster-info.adoc b/modules/rest-api/pages/backup-get-cluster-info.adoc index 193d0806ad..3f9f4804e1 100644 --- a/modules/rest-api/pages/backup-get-cluster-info.adoc +++ b/modules/rest-api/pages/backup-get-cluster-info.adoc @@ -8,7 +8,7 @@ == HTTP Methods and URIs ---- -GET /cluster/self +GET /api/v1/cluster/self ---- [#description] @@ -20,12 +20,15 @@ Returns a JSON document that contains subdocuments for active, imported, and arc == Curl Syntax ---- -curl -X GET http://:8097/cluster/self - -u : +curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/cluster/self + -u $USERNAME:$PASSWORD ---- Only the host cluster (`self`) can be queried. -The `username` and `password` must be those of a user with the `Full Admin` role. + +== Required Permissions + +Full Admin, Backup Admin, or Read-Only Admin role. [#responses] == Responses @@ -51,13 +54,16 @@ An internal error that prevents return of the repository-information returns `50 The following call requests the list of repositories currently defined on the cluster: +[source, curl] ---- -curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/cluster/self \ +curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self \ -u Administrator:password ---- If successful, the call returns `200 OK`, and an object whose initial part may appear as follows: + +[source, json] ---- { "name": "self", @@ -122,6 +128,10 @@ If successful, the call returns `200 OK`, and an object whose initial part may a . . . + } + } + } +} ---- The cluster is thus shown to contain a single imported repository, no archived repositories, and a number of active repositories, two of which can be identified in the fragment shown. @@ -129,6 +139,6 @@ The cluster is thus shown to contain a single imported repository, no archived r [#see-also] == See Also -An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. -Information on using the Backup Service REST API to create a repository is provided in xref:rest-api:backup-create-repository.adoc[Create a Repository]. +* For an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. +* For a step-by-step guide to using Couchbase Server Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* For information about using the Backup Service REST API to create a repository, see xref:rest-api:backup-create-repository.adoc[Create a Repository]. diff --git a/modules/rest-api/pages/backup-manage-config.adoc b/modules/rest-api/pages/backup-manage-config.adoc index d22c231920..456fdc898c 100644 --- a/modules/rest-api/pages/backup-manage-config.adoc +++ b/modules/rest-api/pages/backup-manage-config.adoc @@ -1,5 +1,6 @@ = Manage Backup Configuration -:description: The rotation period and size for Backup Service configuration data can be set and returned by means of the REST API. +:description: This method lets you get and set the rotation size for Backup Service history. + [abstract] {description} @@ -7,64 +8,73 @@ [#http-methods-and-uris] == HTTP Methods and URIs +Get the current rotation configuration: + +---- +GET /api/v1/config ---- -POST /config -PUT /config +Apply a new configuration: -GET /config ---- +POST /api/v1/config +---- + +// Commenting out because I can't get this to work. --Gary +// Edit an existing configuration: +//---- +//PUT /config +//---- + +.POST Parameter +[cols="2,3,2"] +|=== +|Name | Description | Schema + +| `history_rotation_size` +| The maximum size of the backup history can grow to before the Backup Service starts removing older history. +| Integer value between 5 and 200 -[#description] -== Description +|=== -Used with the `POST` http method, the `/config` URI establishes, with `PUT` modifies, and with `GET` retrieves the rotation limits for Backup Service configuration data. [#curl-syntax] == Curl Syntax ---- -curl -X POST http://:8097/config - -u -u : - -d +curl -X GET http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/config + -u $USERNAME:$PASSWORD -curl -X PUT http://:8097/config - -u -u : - -d - -curl -X GET http://:8097/config - -u -u : - -d +curl -X POST http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/config + -u $USERNAME:$PASSWORD + -d '{"history_rotation_size":$HISTORY_ROTATION_SIZE}' ---- -The `username` and `password` must be those of a user with the `Full Admin` role. -The `rotation-settings` must be specified as a JSON payload. -The settings are: - -* `historyRotationPeriod`. -A number of days. -The default value is 30, the minimum 1, the maximum 365. -When this number of days has elapsed, the configuration file is rotated. - -* `historyRotationSize`. -A number of megabytes. -The default value is 50, the minimum 5, the maximum 200. +== Required Permissions -When this size is reached, the configuration file is rotated. +To call this method via GET: Full Amin, Backup Admin, or Read-Only Admin. -Note that the configuration file grows in size due to the progressive accumulation of task-history for the cluster. -On rotation, a sequentially numbered copy of the current configuration file is made. -The current configuration file is then deleted, and a new file is created when new data is written. +To call this method via POST: Full Admin or Backup Admin. [#responses] == Responses -For all three http methods, success returns `200 OK`. -If an improper value is expressed, `400 Bad Request` is returned, with a message such as the following: `{"status":400,"msg":"rotation size has to be between 5 and 200"}`. +|=== +|Value | Description + +| `200 OK` and when calling via GET, a JSON object containing the current settings. +| Successful call. + +| `400 Bad Request` plus the JSON message `{ "status": 400, "msg": "Rotation size has to be between 5 and 200"}` +| Returned when trying to set the rotation size to an invalid value. + +| `401 Unauthorized` +| Authorization failure due to incorrect username or password. -Failure to authenticate returns `401 Unauthorized`. -An internal error that prevents return or modification of the limits returns `500 Internal Server Error`. +| `403 Forbidden`, plus a JSON message explaining the minimum permissions. +| The provided username has insufficient privileges to call this method. +|=== [#examples] == Examples @@ -72,21 +82,21 @@ An internal error that prevents return or modification of the limits returns `50 The following call returns the current configuration limits: ---- -curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/config \ +curl -v -X GET http://127.0.0.1:8097/api/v1/config \ -u Administrator:password ---- If successful, the call returns `200 OK`, and the following object: ---- -{"history_rotation_period":30,"history_rotation_size":50} +{"history_rotation_size":50} ---- -The following call modifies both rotation period and size: +The following call modifies the rotation size: ---- -curl -v -X POST http://127.0.0.1:8091/_p/backup/api/v1/config -u Administrator:password \ ---data '{"history_rotation_period":32,"history_rotation_size":51}' +curl -v -X POST http://127.0.0.1:8097/api/v1/config -u Administrator:password \ +-d '{"history_rotation_size":51}' ---- Success returns `200 OK`. @@ -94,5 +104,5 @@ Success returns `200 OK`. [#see-also] == See Also -An overview of the Backup Service is provided in xref:learn:services-and-indexes/services/backup-service.adoc[Backup Service]. -A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore]. +* For an overview of the Backup Service, see xref:learn:services-and-indexes/services/backup-service.adoc[]. +* For a step-by-step guide to using Couchbase Server Web Console to configure and use the Backup Service, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[]. From 967e2b0f009a216cc4ee712a2bd4c34d6e319445 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 10 May 2024 09:18:23 -0400 Subject: [PATCH 16/16] Updating What's New list of impacted REST APIs --- modules/introduction/partials/new-features-76_2.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/modules/introduction/partials/new-features-76_2.adoc b/modules/introduction/partials/new-features-76_2.adoc index 9b81d9b177..d7dcb6445d 100644 --- a/modules/introduction/partials/new-features-76_2.adoc +++ b/modules/introduction/partials/new-features-76_2.adoc @@ -1,8 +1,11 @@ [#backup_762] === Backup -* Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following REST API endpoints: +* Users with the xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin] role can now read backup information from the following Backup Service REST API endpoints: + +** xref:rest-api:backup-get-cluster-info.adoc[`/api/v1/cluster/self`] +** xref:rest-api:backup-manage-config.adoc[`/api/v1/config`] +** xref:rest-api:backup-get-repository-info.adoc[`/api/v1/cluster/self/repository/{repo-state}`] +** xref:rest-api:backup-get-task-info.adoc[`/api/v1/cluster/self/repository/{repo-state}/{task-name}/taskHistory`] +** xref:rest-api:backup-get-plan-info.adoc[`/api/v1/plan/`] -** xref:rest-api:backup-get-repository-info.adoc[`/cluster/self/repository/active`] -** xref:rest-api:backup-get-task-info.adoc[`/cluster/self/repository/active/JOB-NAME/taskHistory`] -** xref:rest-api:backup-get-plan-info.adoc[`/plan/PLAN-NAME`]