POST /manage/v2/forests

Summary

Create a new forest, including replicas if specified. If a database id or
database is included, attach the new forest(s) to the database. For an example, see
Preliminary Configuration Procedures in the Scripting Administrative Tasks Guide.

URL Parameters

format

The format of the returned data. Can be either
html, json, or xml (default). This value overrides
the Accept header if both are present.

wait-for-forest-to-mount

Whether or not to wait for the new forest to mount before sending a response to
this request. Allowed values: true (default) or false.

Request Headers

Accept

The expected MIME type of the response. If the
format parameter is present, it takes precedence over the Accept header.
Allowed values: application/xml, application/json, and
text/html.

Content-Type

The MIME type of the data in the request
body, either application/xml or application/json.

Response

Required Privileges

This operation requires the manage-admin role, or the following
privilege:

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

The payload can specify either replica forests or failover hosts, but not both. If
replicas are specified in the POST body, then replication is enabled by default.

Newly created forests are enabled by default.

Setting range boundaries for the
forest in the POST body does not modify the configuration of the database to which the
forest is attached.

The structure of the data in the POST body is shown below. You
must include at least forest-name and host. If replicas are
included, the configuration data for each replica must include at least
replica-name and host.

Note: The properties described
here are for XML payloads. In general they are the same for JSON, with the exception that,
in JSON, failover-hosts and forest-replicas are expressed in
singular form. For example, in JSON, failover-hosts is instead
failover-host and the format is: "failover-host":["hostname"].

The data in the POST body must be valid according to the schema type "forest-properties"
in the "manage-forest-properties.xsd" schema. JSON payloads are internally converted to
XML before validation.

forest-name

The forest name.

host

A host name or id.

database

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

availability

Availability of the forest data.

rebalancer-enable

Enable automatic rebalancing after configuration changes.

range

Range configuration for the range assignment policy.

This is a complex structure with the following children:

lower-bound

The lower bound of the range on the forest.

upper-bound

The upper bound of the range on the forest.

failover-hosts

A list of hosts for shared disk failover.

This is a complex structure with the following children:

failover-host

A host name or id for shared disk failover.

failover-enable

Enable assignment to a failover host if the primary host is down.

forest-backups

Backups scheduled for this forest.

This is a complex structure with the following children:

forest-backup

A scheduled forest backup.

This is a complex structure with the following children:

backup-id

The backup ID.

backup-enabled

Whether or not a backup is enabled

backup-directory

The backup directory pathname.

backup-type

What type of backup is this.

backup-period

How often this backup should run (every n months, weeks, days, hours or minutes).