Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

cbbackupmgr config

    +

    Creates and configures a new backup repository

    SYNOPSIS

    cbbackupmgr config [--archive <archive_dir>] [--repo <repo_name>]
                   [--include-buckets <buckets>] [--exclude-buckets <buckets>]
                   [--disable-bucket-config] [--disable-views] [--disable-eventing]
                   [--disable-gsi-indexes] [--disable-ft-indexes]
                   [--disable-data] [--vbucket-filter <integer_list>]
                   [--disable-analytics] [--disable-ft-alias]
                   [--obj-access-key-id <access_key_id>] [--obj-cacert <cert_path>]
                   [--obj-endpoint <endpoint>] [--obj-no-ssl-verify]
                   [--obj-region <region>] [--obj-staging-dir <staging_dir>]
                   [--obj-secret-access-key <secret_access_key>]
                   [--s3-force-path-style] [--s3-log-level <level>]

    DESCRIPTION

    Creates a new backup repository with a new backup configuration. The configuration created is used for all backups in this backup repository.

    By default a backup configuration is created that will backup all buckets in the cluster. Each bucket will have its bucket configuration, views definitions, gsi index definitions, full-text index definitions, and data backed up. Specifying various flags, the config command can modify the configuration to backup a subset of the data.

    Once a backup repository is created its configuration cannot be changed.

    OPTIONS

    Below are a list of required and optional parameters for the config command.

    Required

    -a,--archive <archive_dir>

    The directory where the new backup repository will be created. If it does not already exist, an attempt will be made to create it. When configuring an archive in S3 you must prefix the archive path with s3://${BUCKET_NAME}/.

    -r,--repo <repo_name>

    The name of the new backup repository.

    Optional

    --include-buckets <buckets>

    Modifies the repository configuration to only backup the buckets included in the coma separated list <buckets>. This flag can’t be specified at the same time as the --exclude-buckets flag.

    --exclude-buckets <buckets>

    Modifies the repository configuration to backup all buckets not specified in the <buckets>. This flag can’t be specified at the same time as the --exclude-buckets flag. Takes a comma separated list of buckets.

    --disable-views

    Modifies the repository configuration to disable backing up view definitions for all buckets.

    --disable-gsi-indexes

    Modifies the repository configuration to disable backing up gsi index definitions for all buckets.

    --disable-ft-indexes

    Modifies the repository configuration to disable backing up full-text index definitions for all buckets.

    --disable-ft-alias

    Modifies the repository configuration to disable backing up full-text alias definitions.

    --disable-data

    Modifies the repository configuration to disable backing up all key-value data for all buckets.

    --disable-analytics

    Modifies the repository configuration to disable backing up analytics data.

    --disable-eventing

    Modifies the repository configuration to disable backing up the Eventing service metadata.

    --vbucket-filter <list>

    Specifies a list of VBuckets that should be backed up in the repo being created. VBuckets are specified as a comma separated list of integers. If this parameter is not set then all vbuckets are backed up. The comma separated list can also take sequences denoted as e.g: 0-5 this is equivalent to 0,1,2,3,4,5.

    Cloud integration

    Required

    --obj-staging-dir <staging_dir>

    When performing an operation on an archive which is located in the cloud such as AWS, the staging directory is used to store local meta data files. This directory can be temporary (it’s not treated as a persistent store) and is only used during the backup. NOTE: Do not use /tmp as the obj-staging-dir. See Disk requirements in cbbackupmgr-cloud for more information.

    Optional

    --obj-access-key-id <access_key_id>

    The access key id which has access to your chosen object store. This option can be omitted when using the shared config functionality provided by your chosen object store. Can alternatively be provided using the CB_OBJSTORE_ACCESS_KEY_ID environment variable.

    --obj-cacert <cert_path>

    Specifies a CA certificate that will be used to verify the identity of the object store being connected to.

    --obj-endpoint <endpoint>

    The host/address of your object store.

    --obj-no-ssl-verify

    Skips the SSL verification phase when connecting to the object store. Specifying this flag will allow a connection using SSL encryption, but you are vulnerable to a man-in-the-middle attack.

    --obj-region <region>

    The region in which your bucket/container resides. For AWS this option may be omitted when using the shared config functionality. See the AWS section of the cloud documentation for more information.

    --obj-secret-access-key <secret_access_key>

    The secret access key which has access to you chosen object store. This option can be omitted when using the shared config functionality provided by your chosen object store. Can alternatively be provided using the CB_OBJSTORE_SECRET_ACCESS_KEY environment variable.

    AWS S3 Options

    Optional
    --s3-force-path-style

    By default the updated virtual style paths will be used when interfacing with AWS S3. This option will force the AWS SDK to use the alternative path style URLs which are often required by S3 compatible object stores.

    --s3-log-level <level>

    Set the log level for the AWS SDK. By default logging will be disabled. Valid options are debug, debug-with-signing, debug-with-body, debug-with-request-retries, debug-with-request-errors, and debug-with-event-stream-body.

    EXAMPLES

    The config command is used to create a backup repository and define the repositories backup configuration. In the examples below, the backup archive is located at /data/backups. Since this is the first backup repository we are creating in a new backup archive, we need to ensure that /data/backups is an empty directory. Archives are created automatically if an archive doesn’t already exist at the archive path, but are only created if the directory at that path is empty. In order to create a backup repository called "example" with the default configuration use the following command:

    $ cbbackupmgr config -a /data/backups -r example

    Upon creation of a new backup repository there will be a new directory in the backup archive containing a backup configuration. You can see this new directory using the cbbackupmgr-list[1] command.

    $ cbbackupmgr list -a /data/backups
Size      Items          Name
0B        -              + example

    Using the optional parameters of the create command, you can modify the backup configuration settings. To create a backup repository with a backup configuration that only backs up the buckets "airline_data" and "ticket_prices" and does not back up up bucket configuration data, you can run the following:

    $ cbbackupmgr config -a /data/backups -r example \
 --include-buckets airline_data,ticket_prices --disable-bucket-config

    To create a backup repository with a backup configuration that backs up only data on all buckets, you can run the following command:

    $ cbbackupmgr config -a /data/backups -r example --disable-bucket-config \
 --disable-views --disable-gsi-indexes --disable-ft-indexes

    When creating an archive in an object store such as S3 due care must be taken to ensure that the provided directory is empty and can be managed by cbbackupmgr.

    $ cbbackupmgr config -a s3://bucket/archive -r repo --obj-staging-dir /staging

    DISCUSSION

    Though not required, it is recommended that there is a single backup repository per cluster. Backup repositories are managed so that all backups can be taken incrementally and merged together as backup data ages. Backing up in this manner allows backups to transfer the least amount of data necessary which reduces back up time and cluster resource usage. For more details on backup strategies see cbbackupmgr-strategies[7].

    When a backup repository is created, it should only be modified by the cbbackupmgr utility. Any modifications done outside of this utility can cause corruption of backup files.

    ENVIRONMENT AND CONFIGURATION VARIABLES

    CB_ARCHIVE_PATH

    Specifies the path to the backup archive. If the archive path is supplied as a command line argument then this value is overridden.

    CB_OBJSTORE_STAGING_DIRECTORY

    Specifies the path to the staging directory. If the --obj-staging-dir argument is provided in the command line then this value is overridden.

    CB_OBJSTORE_REGION

    Specifies the object store region. If the --obj-region argument is provided in the command line then this value is overridden.

    CB_OBJSTORE_ACCESS_KEY_ID

    Specifies the object store access key id. If the --obj-access-key-id argument is provided in the command line this value is overridden.

    CB_OBJSTORE_SECRET_ACCESS_KEY

    Specifies the object store secret access key. If the --obj-secret-access-key argument is provided in the command line this value is overridden.

    CB_AWS_ENABLE_EC2_METADATA

    By default cbbackupmgr will disable fetching EC2 instance metadata. Setting this environment variable to true will allow the AWS SDK to fetch metadata from the EC2 instance endpoint.

    FILES

    backup-meta.json

    The config command creates a backup configuration file in the backup repository called backup-meta.json. This file contains the backup configuration for all backups run in the backup repository it was created in. It should never be modified and treated as a read-only file.

    SEE ALSO

    cbbackupmgr-list, cbbackupmgr-strategies, cbbackupmgr-cloud

    CBBACKUPMGR

    Part of the cbbackupmgr suite