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.

cbbackupmgr examine

    +

    Searches one or more backups by key for a specific document

    SYNOPSIS

    cbbackupmgr examine [--archive <archive_dir>] [--repo <repo_name>]
                    [--bucket <bucket>] [--key <key_name>]
                    [--tombstones] [--backups <backup_list>] [--json]
                    [--no-meta] [--no-xattrs] [--no-value] [--hex-meta]
                    [--hex-xattrs] [--hex-value] [--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

    The examine command is used to locate a document from a bucket which is in one or more incremental backups. If the document is found in multiple backups (at different stages in its history) all will be returned. You may optionally supply the name of the specific backup you wish to examine; however, in this case only one document will be returned.

    OPTIONS

    Below is a list of parameters for the examine command.

    Required

    -a,--archive <archive_dir>

    The archive directory to examine. When using examine against an archive stored in S3 prefix the archive path with s3://${BUCKET_NAME}/

    -r,--repository <repo_name>

    The name of the backup repository to examine.

    --bucket <bucket>

    The bucket in which to search for the document.

    -k,--key

    The name of the key you are trying to find.

    Optional

    -B,--backups <backup_range>

    The name of a specific backup or a comma separated pair of dates/indices which are examined as a range. See the BACKUP RANGES section for more information on accepted date/index pairs.

    -t,--tombstones

    By default a 'NotFoundError' will be raised if the document for a given key has been deleted. If '--tombstones' is provided, the document tombstone will be returned.

    -j,--json

    Return any output as a JSON structure.

    --no-meta

    Do not return any of the documents metadata.

    --no-xattrs

    Do not return any of the documents extended attributes.

    --no-value

    Do not return the documents value.

    --hex-meta

    Return the metadata encoded in hex.

    --hex-xattrs

    Return the extended attributes encoded in hex.

    --hex-value

    Return the value encoded in hex.

    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 your 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. Specifiying 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.

    BACKUP RANGES

    The examine command accepts a pair of dates or indices using the --backups argument which can be used to refine the search space for your data.

    When given the backup range 0,5 examine will search all of the backups in chronological order starting from the first backup, finishing with the fifth backup.

    When given the backup range 20-08-2019,23-08-2019 examine will search in all the backups which fall within these two dates. Note that the format must be 'day-month-year'; this means that '01-30-19' is an invalid date and will be rejected by examine.

    Examine also accepts a backup range using the names of backups e.g. '2019-08-23T09_36_56.957232625Z'. Therefore, given the backup range 2019-08-20T11_39_34.232308323Z, 2019-08-23T09_36_56.957232625Z examine will search in any backups which fall within these two backups.

    EXAMPLES

    The examine command is used to determine if a certain backup/backups contains a specific document.

    $ cbbackupmgr examine -a /data/backups -r example --bucket default -k document_001
Key: document_001
  Backup: 2019-07-19T15_54_29.251286016Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1563551624866037760,"revseqno":1,"datatype":1}
  Value: {"type":"example"}

    By using the optional --backups argument you can refine the search space by limiting the search to a set range of backups.

    $ cbbackupmgr examine -a /data/backups -r example --bucket default -k document_001 --backups '20-08-2019,23-08-2019'
Key: document_001
  Backup: 2019-08-20T15_54_29.251286016Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1563551624866037760,"revseqno":1,"datatype":1}
  Value: {"type":"example"}

Key: document_001
  Backup: 2019-08-22T12_36_20.381276326Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1566554379279592866,"revseqno":2,"datatype":1}
  Value: {"type":"example", "subtype": "examine-example"}

    By using the optional arguments provided by the examine command you can modify how the document is returned.

    $ cbbackupmgr examine -a /data/backups -r example --bucket default -k document_001 --json
[
  {
    "backup": "2019-07-19T15_54_29.251286016Z",
    "key": "document_001",
    "value": {
      "type": "example"
    },
    "meta": {
      "flags": 33554438,
      "expiry": 0,
      "locktime": 0,
      "cas": 1563551624866037800,
      "revseqno": 1,
      "datatype": 1
    },
    "xattrs": {},
    "deleted": false
  }
]

$ cbbackupmgr examine -a /data/backups -r example --bucket default -k document_001 --hex-value
Key: document_001
  Backup: 2019-07-19T15_54_29.251286016Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1563551624866037760,"revseqno":1,"datatype":1}
  Value:
    00000000  7b 0a 20 20 20 20 22 74  79 70 65 22 3a 20 22 65  |{.    "type": "e|
    00000010  78 61 6d 70 6c 65 22 0a  7d                       |xample".}|

    The default behavior when examine encounters a deleted document (tombstone) is to inform the user that no document with that key is contained in the backup; this behavior can be modified by using the --tombstones flag.

    $ cbbackupmgr examine -a /data/backups -r example --bucket default -k document_001 --tombstones
Key: document_001
  Backup: 2019-07-19T15_54_29.251286016Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1563551624866037760,"revseqno":1,"datatype":1}
  Value: {"type":"example"}

Key: document_001
  Backup: 2019-07-19T16_16_39.09322082Z
  Deleted: true
  Meta: {"flags":0,"expiry":0,"locktime":0,"cas":1563552985754632192,"revseqno":2,"datatype":0}

    All of the optional arguments provided by examine are not mutually exclusive and can be used in conjunction with one another.

    You can also use examine on archives which are stored in AWS S3 and only the minimum amount of data required to get the chosen key will be downloaded.

    $ cbbackupmgr examine -a s3://bucket/archive -r example --bucket default -k document_001 --obj-staging-dir /data/backups
Key: document_001
  Backup: 2019-07-19T15_54_29.251286016Z
  Deleted: false
  Meta: {"flags":33554438,"expiry":0,"locktime":0,"cas":1563551624866037760,"revseqno":1,"datatype":1}
  Value: {"type":"example"}

    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.

    SEE ALSO

    cbbackupmgr-cloud

    CBBACKUPMGR

    Part of the cbbackupmgr suite