This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Database management with VCluster

You can manage your database with VCluster instead of using AdminTools. There are two parts to VCluster: VCluster CLI and VCluster UI.

You can manage your database with VCluster instead of using AdminTools. There are two parts to VCluster: VCluster CLI and VCluster UI.

1 - Database management with VCluster CLI

The VCluster CLI is a tool for administering your database.

The VCluster CLI is a tool for administering a single database. This tool is bundled with OpenText™ Analytics Database installations. VCluster CLI communicates with database nodes by leveraging the REST APIs provided by Node Management Agent and HTTPS service.

Prerequisites

To use the VCluster CLI, you must first configure the Node Management Agent (NMA), including running the following command on all nodes:

$ /opt/vertica/bin/manage_node_agent.sh start node_management_agent

Best practices

The majority of VCluster CLI commands use the configuration file, which is automatically created when you create a database. You should always use this configuration file when using VCluster CLI, either by ensuring that the configuration file is in the default location (/opt/vertica/config/vertica_cluster.yaml) or specifying it with --config.

To recreate a configuration file, use manage_config recover. This can be useful if you lose your configuration file or if it becomes corrupted.

To view your current configuration file, use manage_config show.

1.1 - Common administrative tasks

lorem ipsum

Stop, restart, and revive

This procedure can be useful in cases where you want to change AWS instances to save money. For example, you can use us-east instances during the day and switch to us-west instances at night.

This example uses the database created by the following command using the region us-east-1:

$ vcluster create_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --catalog-path /scratch_b/qa --data-path /scratch_b/qa --shard-count 4 --communal-storage-location s3://testbucket/test_db --depot-path /path/to/depot --depot-size 20G --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=key:secret,awsenablehttps=0,awsregion=us-east-1,awsendpoint=myhost:9000 --password "" --skip-package-install
✔ Check NMA service health
...
✔ Synchronize catalog with communal storage
[INFO] Successfully created a database with name [test_db]

  1. Stop the database:

    $ Stop DB
/opt/vertica/bin/vcluster stop_db --db-name test_db --config /opt/vertica/config/vertica_cluster.yaml --password ""
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Collect information for all up nodes
✔ Synchronize catalog with communal storage
✔ Stop database
✔ Verify database is not running
[INFO] Successfully stopped a database with name test_db

  2. Revive the database. For this example, the database is revived into a different region:

    $ vcluster revive_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --communal-storage-location s3://testbucket/test_db --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=key:secret,awsenablehttps=0,awsregion=us-west-1,awsendpoint=myhost:9000
✔ Check NMA service health
✔ Verify database is running
✔ Download cluster_config.json
✔ Create necessary directories on database hosts
✔ Get network profile of cluster
✔ Load remote catalog
[INFO] Successfully revived database test_db

  3. Start the database:

    $ /opt/vertica/bin/vcluster start_db --db-name test_db --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --catalog-path /path/to/catalog --config /opt/vertica/config/vertica_cluster.yaml --config-param awsauth=miniokey:miniosecret,awsenablehttps=0,awsregion=us-east-1,awsendpoint=qastress-39:9000 --password ""
✔ Check NMA service health
✔ Collect nodes information
✔ Download cluster_config.json
✔ Check NMA service health
✔ Verify database is running
✔ Read catalog
✔ Check Vertica version
✔ Get contents of vertica.conf
✔ Get contents of spread.conf
✔ Start 3 node(s)
✔ Wait for 3 node(s) to come up: all nodes are up
✔ Synchronize catalog with communal storage
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
[INFO] Started database test_db

Test on sandboxed subclusters

You can create sandboxed subclusters and perform tests on them without affecting your production database. For details, see Subcluster sandboxing:

  1. Add the subcluster sc1 which contains nodes 192.2.0.4 and 192.2.0.5:

    $ vcluster add_subcluster  --subcluster sc1 --db-name test_db --password "" --hosts 192.2.0.1,192.2.0.2,192.2.0.3 --control-set-size 1 --new-hosts 192.2.0.4,192.2.0.5
✔ Collect cluster information
✔ Check NMA service health
...
✔ Initiate rebalance of subcluster shards
[INFO] Successfully added subcluster sc1 with nodes [192.2.0.3,192.2.0.4] to database **test_db**

  2. Sandbox the subcluster sc1 with a the new sandbox sand:

    $ vcluster sandbox_subcluster --subcluster sc1 --sandbox sand -p "" --config /opt/vertica/config/vertica_cluster.yaml
✔ Collect information for all up nodes
✔ Find all subclusters and record their sandboxing information
✔ Convert subcluster into sandbox in catalog system
✔ Wait for subcluster nodes to come up
[INFO] Successfully sandboxed subcluster sc1 as sand

  3. Verify that your nodes were sandboxed with list_all_nodes. The following command is run from outside the sandbox sand, so the state of nodes in sand are listed as UNKNOWN:

    $ vcluster list_all_nodes --config /opt/vertica/config/vertica_cluster.yaml -p ""
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Check NMA service health
✔ Read Vertica version
✔ Check node state from running database
[
{
"address": "192.0.2.1",
"name": "v_test_db_node0001",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0001_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.2",
"name": "v_test_db_node0002",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0002_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.3",
"name": "v_test_db_node0003",
"state": "UP",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0003_catalog/Catalog",
"subcluster": "default_subcluster",
"sandbox": "",
"is_primary": true,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.4",
"name": "v_test_db_node0004",
"state": "UNKNOWN",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0004_catalog/Catalog",
"subcluster": "sc1",
"sandbox": "sand",
"is_primary": false,
"version": "v24.3.0-20240613"
},
{
"address": "192.0.2.5",
"name": "v_test_db_node0005",
"state": "UNKNOWN",
"catalog_path": "/scratch_b/qa/test_db/v_test_db_node0005_catalog/Catalog",
"subcluster": "sc1",
"sandbox": "sand",
"is_primary": false,
"version": "v24.3.0-20240613"
}
]
[INFO] Successfully listed all nodes

  4. After you finish testing your sandboxed subcluster, unsandbox it:

    $ vcluster unsandbox_subcluster --subcluster sc1 -p "" --config /opt/vertica/config/vertica_cluster.yaml
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Check NMA service health
✔ Collect information for all up nodes
✔ Stop node
✔ Wait for subcluster nodes to come down
✔ Convert sandboxed subcluster into regular subcluster in catalog
✔ Delete database directories
✔ Check Vertica version
✔ Get startup command for unsandboxed nodes
✔ Start 0 node(s)
✔ Wait for subcluster nodes to come up
[INFO] Successfully unsandboxed subcluster sc1

1.2 - VCluster commands

lorem ipsum

This section contains reference material and simple examples for various vcluster commands. These examples assume that you have fulfilled the prerequisites for using vcluster. For more detailed examples, see Common administrative tasks.

You can also use the --help flag on any command or vcluster itself to view the manual.

For the vcluster manual:

$ vcluster --help

For help with any given command, use vcluster command --help or vcluster help command. For example:

$ vcluster create_db --help
$ vcluster help create_db

1.2.1 - add_node

Adds one or more user-specified hosts as nodes to an existing database. You cannot add nodes to a sandboxed subcluster.

Adds one or more user-specified hosts as nodes to an existing database. You cannot add nodes to a sandboxed subcluster.

Syntax

vcluster add_node options

Required options

--catalog-path string
The absolute path to the catalog directory.
{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--new-hosts hostname_or_ip [,...]
A comma-separated list of hosts to add to the database.

Options

--add-node-timeout int
The time, in seconds, to wait for the specified nodes to be added.

Default: 300

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--data-path string
The absolute path to the data directory. This should be the same for all nodes in the database.
--depot-path string
[Eon only] The absolute path to depot directory.
--depot-size string
[Eon only] Size of depot in one of the following formats:
  • integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
  • integer%, which expresses the depot size as a percentage of the total disk size.
--force-removal
Whether to delete any existing database directories in the new hosts before attempting to add them.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--node-names string
[Use only with support guidance] A comma-separated list of node names that exist in the cluster.
{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--skip-rebalance-shards
[Eon only] Whether to skip shard rebalancing.
--subcluster string
[Eon only] The name of the subcluster to which the host(s) should be added. This string must conform to the format used for database names.

Default: Default subcluster

--verbose
Shows the details of VCluster run in the console.

Examples

To add the node 192.2.0.4:

$ vcluster add_node --new-hosts 192.2.0.4

To add multiple nodes:

$ vcluster add_node --new-hosts 192.2.0.4,192.2.0.5

1.2.2 - add_subcluster

Adds a new subcluster to an Eon Mode database.

Adds a new subcluster to an Eon Mode database. For details, see Creating subclusters.

Syntax

vcluster add_subcluster options

Required options

--catalog-path string
The absolute path to the catalog directory.
{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string
The name of the new subcluster. This string must conform to the format used for database names.

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--control-set-size int
The number of control nodes in the subcluster.

Default: -1 (All nodes in the subcluster are control nodes)

--create-storage-locations
Indicates whether the sandbox can create its own storage locations.
--data-path string
The absolute path to the data directory. This should be the same for all nodes in the database.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--depot-path string
[Eon only] The absolute path to depot directory.
--depot-size string
[Eon only] Size of depot in one of the following formats:
  • integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
  • integer%, which expresses the depot size as a percentage of the total disk size.
--for-upgrade
Indicates whether the sandbox is used for an online upgrade.
--force-removal
Whether to delete any existing database directories in the new hosts before attempting to add them.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--is-primary
Whether the new subcluster should be a primary subcluster. If this option is omitted, new subclusters are secondary.
--isolate-metadata
Specifies whether to isolate the metadata of the sandboxed subcluster.
--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--like string
Clones the configuration from an existing subcluster. Cannot be used with --is-primary or --control-set-size.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--new-hosts string[,...]
A comma-separated list of hosts or IP addresses to add to the subcluster.
{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--sandbox string
Name of the sandbox where the subcluster will be added.
--save-restore-point
Indicates whether a restore point should be saved when creating the sandbox.
--skip-rebalance-shards
[Eon only] Whether to skip shard rebalancing.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To add a subcluster with a config file:

  vcluster add_subcluster --subcluster sc1 \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --is-primary --control-set-size 1 \
    --password "PASSWORD"

To add a subcluster with user input:

  vcluster add_subcluster --subcluster sc1 --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --is-primary --control-set-size -1 \
    --password "PASSWORD"

To add a subcluster and new nodes in the subcluster with a config file:

  vcluster add_subcluster --subcluster sc1 \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --is-primary --control-set-size 1 --new-hosts 192.0.2.3 \
    --password "PASSWORD"

To add a subcluster and new nodes in the subcluster with user input:

  vcluster add_subcluster --subcluster sc1 --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --is-primary --control-set-size -1 --new-hosts 192.0.2.3 \
    --password "PASSWORD"

To clone properties from an existing subcluster (empty to empty):

vcluster add_subcluster --subcluster sc2 --like sc1

To clone properties and add a single node (must match source node count):

cluster add_subcluster --subcluster sc2 --like sc1 --new-hosts 192.0.2.5

To clone properties and add multiple nodes (must match source node count):

vcluster add_subcluster --subcluster sc2 --like sc1 --new-hosts 192.0.2.5,192.0.2.6

1.2.3 - completion

Creates a tab-completion script for a specified shell.

Creates a tab-completion script for a specified shell.

A tab-completion script for your default shell is automatically generated and configured when you install OpenText™ Analytics Database, so completion is only necessary in cases where you either change shells or want to use vcluster from a non-OpenText™ Analytics Database node.

Syntax

vcluster completion subcommand

Subcommands options

shell
The shell for which to generate a completion script, one of the following:
  • bash
  • fish
  • powershell
  • zsh

Examples

For example, to configure tab-completion for bash on Linux, generate the tab-completion script, redirecting its output to a new file vcluster_tab_completion:

$ vcluster completion bash > /etc/bash_completion.d/vcluster

Similarly, for bash on macOS:

$ vcluster completion bash > $(brew --prefix)/etc/bash_completion.d/vcluster

1.2.4 - create_db

Creates a new database and its associated configuration file for use with other vcluster commands.

Creates a new database and its associated configuration file for use with other vcluster commands.

Syntax

vcluster create_db { options }

Required options

--catalog-path string
The absolute path to the catalog directory.
--data-path string
The absolute path to the data directory. This should be the same for all nodes in the database.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--hosts strings
A comma-separated list of hosts in the database.

Eon options

The following options are required for creating Eon Mode databases, the database mode primarily supported by vcluster:

--communal-storage-location string
[Eon only] The absolute path of your communal storage location.
--shard-count int
[Eon only] The number of shards in the database.

Options

--broadcast
Configures Spread to use UDP broadcast traffic between nodes on the same subnet. Do not combine this option with --point-to-point.

Up to 80 Spread daemons are supported by broadcast traffic. You can exceed the 80-node limit by using large cluster mode, which only installs the Spread daemon on a subset of your nodes.

Default: Disabled

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -c | --config } string
The path to write the configuration file.

Default: /opt/vertica/config/vertica_cluster.yaml

--config-param PARAMETER=VALUE[,...]
A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:
  • AWSAuth
  • AWSEndpoint
  • AWSEnableHttps
  • AWSRegion
--depot-path string
[Eon only] The absolute path to depot directory.
--depot-size string
[Eon only] Size of depot in one of the following formats:
  • integer{K|M|G|T}, where K is kilobytes, M is megabytes, G is gigabytes, and T is terabytes.
  • integer%, which expresses the depot size as a percentage of the total disk size.
--force-cleanup-on-failure
Deletes directories created by create_db upon failure.
--force-overwrite-file
Overwrites the current configuration file, if any.
--force-removal-at-creation
Deletes existing database directories before attempting to create the database.
--get-aws-credentials-from-env-vars
[Eon only] Retrieves AWS credentials from the following environment variables:
  • $AWS_ACCESS_KEY_ID
  • $AWS_SECRET_ACCESS_KEY
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--large-cluster int
Enables the large cluster layout and sets the number of control nodes. The effect of this option is slightly different on Enterprise and Eon databases. For details, see Enabling large cluster.

Default: -1 (Disabled)

--license string
The absolute path to a license file. The path to this license must be the same on all nodes.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--point-to-point
Configures Spread to use point-to-point communication between all OpenText™ Analytics Database nodes. You should use this option if your nodes are not on the same subnet and for virtual environments. Do not combine this option with --broadcast.

Up to 80 Spread daemons are supported by point-to-point communication. You can exceed the 80-node limit by using large cluster mode, which only installs the Spread daemon on a subset of your nodes.

Default: Enabled

--read-password-from-prompt
Prompts the user to enter the password.
--skip-package-install
Skips installing the packages in /opt/vertica/packages.

Default: Disabled

--startup-timeout int
The time, in seconds, to wait for the nodes to start after database creation.

Default: 300

--verbose
Shows the details of VCluster run in the console.

Examples

Create a database with the nodes 192.0.2.0, 192.0.2.1, and 192.0.2.2 with the password in /password.txt:

$ vcluster create_db --db-name vertica_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --catalog-path /data --data-path /data \
    --password-file password.txt

1.2.5 - drop_db

Drops a stopped database. The effects this command has on your data differs slightly between database modes:

Drops a stopped database. The effects this command has on your data differs slightly between database modes:

  • Enterprise: Deletes the database data (including catalog, data, and depot directories) from all nodes.
  • Eon: Deletes non-communal storage data. Dropped Eon Mode databases can be revived.

The data deleted by this operation cannot be recovered.

Syntax

vcluster drop_db [options]

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--verbose
Shows the details of VCluster run in the console.

Examples

To drop a database:

$ vcluster drop_db --db-name test_db

1.2.6 - help

Prints the help text for any command or subcommand. This is the same as using the --help option.

Prints the help text for any command or subcommand. This is the same as using the --help option.

Syntax

vcluster help command

Commands

command
The command to print help text for.

Options

{ -h | --help }
Prints help text.

1.2.7 - install_packages

Installs the packages in /opt/vertica/packages.

Installs the packages in /opt/vertica/packages. This is useful in cases where packages weren't installed during the database installation (either due to --skip-package-install or an error) or if your existing packages are corrupt.

Syntax

vcluster install_packages options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--force-reinstall
Install the packages even if they are already installed.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string
Writes the output to the specified file instead of STDOUT.

Default: STDOUT

--package string
Select packages using all, default, specific package name, or comma-separated list of package names.

Default: all

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To install default packages (when no --package flag is specified):

vcluster install_packages

To install default packages:

vcluster install_packages --package "default"

To install all packages:

vcluster install_packages --package "all"

To install a specific package:

vcluster install_packages --package ComplexTypes

To install multiple packages (comma-separated):

vcluster install_packages --package "ComplexTypes,kafka,logsearch"

To install default packages with user input:

  vcluster install_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password "PASSWORD"

To force (re)install default packages with config file

  vcluster install_packages --db-name test_db --force-reinstall \
    --config /opt/vertica/config/vertica_cluster.yaml \
    --password "PASSWORD"

1.2.8 - list_all_nodes

Returns the following information on all nodes:

Returns the following information on all nodes:

  • IP address
  • Name
  • State
  • Catalog path
  • Subcluster
  • Sandbox
  • Whether the subcluster is primary
  • Database version

The major states a node can be in are UP and DOWN. Other states are largely transitional.

Syntax

vcluster list_all_nodes options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string
Writes the output to the specified file instead of STDOUT.

Default: STDOUT

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

To list the status of nodes for a password-protected database:

$ vcluster list_allnodes --password testpassword \
  --config /opt/vertica/config/vertica_cluster.yaml

1.2.9 - list_packages

Lists all available packages and their installation status.

Lists all available packages and their installation status. It automatically detects the database state:

  • Database UP: Displays the installation status of each package.

  • Database DOWN: Lists only the packages available on the filesystem.

Syntax

vcluster list_packages options

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The path to the certificate file.

Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string
Writes the output to the specified file instead of STDOUT.

Default: STDOUT

--package string
Select packages using all, default, specific package name, or comma-separated list of package names.

Default: all

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To list all the available packages:

vcluster list_packages

To list all the packages with installation status for a database:

vcluster list_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password <PASSWORD>

To list specfic packages with status:

vcluster list_packages \
    --package default \
    --config <config_file_path> \
    --password <PASSWORD>

1.2.10 - manage_config

lorem ipsum

Displays the contents of or recreates the VCluster configuration file. The configuration file (/opt/vertica/config/vertica_cluster.yaml) is automatically generated when you use create_db.

Syntax

vcluster manage_config subcommand

Subcommands

recover
Recreates the VCluster configuration file based on the configuration of the database.
show
Shows the contents of the current configuration file.

1.2.10.1 - manage_config recover

lorem ipsum

Recreates the vcluster configuration file.

This file is automatically generated in /opt/vertica/config/vertica_cluster.yaml when you use create_db.

Syntax

vcluster manage_config recover options

Required options

--catalog-path string
The absolute path to the catalog directory.
{ -c | --config } string
The path to write the configuration file.

Default: /opt/vertica/config/vertica_cluster.yaml

--hosts strings
A comma-separated list of hosts in the database.

Options

--after-revive
Recovers the configuration file after reviving the database. You should only use this if, after reviving the database, you modify the configuration file manually, which is not recommended.
--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--depot-path string
[Eon only] The absolute path to depot directory.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--overwrite
Overwrites the existing /opt/vertica/config/vertica_cluster.yaml, if any. If a configuration file already exists and this flag is not specified, recover has no effect.
--verbose
Shows the details of VCluster run in the console.

Examples

Recrates the configuration file in the default location for an Eon Mode database:

$ vcluster manage_config recover --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --catalog-path /data --depot-path /data

Recreates the configuration file to a specific path:

$ vcluster manage_config recover --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --catalog-path /data --depot-path /data \
  --config /tmp/vertica_cluster.yaml

1.2.10.2 - manage_config show

lorem ipsum

Displays the contents of the vcluster configuration file.

This file is automatically generated in /opt/vertica/config/vertica_cluster.yaml when you use create_db.

Syntax

vcluster manage_config show options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

{ -h | --help }
Prints help text.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--verbose
Shows the details of VCluster run in the console.

Examples

Show the configuration file in the default location (/opt/vertica/config/vertica_cluster.yaml):

$ vcluster config show

Show the configuration file at the specified location:

$ vcluster config show --config /tmp/vertica_cluster.yaml

1.2.11 - re_ip

Updates the catalog with the IP addresses of your nodes when the database is stopped.

Updates the catalog with the IP addresses of your nodes when the database is stopped. You should run this command when the IP address for a node changes. For details, see Reconfiguring node messaging.

You should always stop the database before running re_ip.

Syntax

vcluster re_ip options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--re-ip-file string
Path to a .json file that maps the old IP addresses to the new IP addresses. This file should only include the IP addresses of nodes that you want to update. This file has the following format: 
[
  {"from_address": "10.20.30.40", "to_address": "10.20.30.41"},
  {"from_address": "10.20.30.42", "to_address": "10.20.30.43"}
]

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--config-param PARAMETER=VALUE[,...]
A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:
  • AWSAuth
  • AWSEndpoint
  • AWSEnableHttps
  • AWSRegion
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--verbose
Shows the details of VCluster run in the console.

Examples

To update the IP addresses with the information in /data/re_ip_map.json:

$ vcluster re_ip --db-name vertica_db --re-ip-file /data/re_ip_map.json

1.2.12 - remove_node

Removes one or more nodes from a database.

Removes one or more nodes from a database.

You cannot remove nodes from a sandboxed subcluster.

Syntax

vcluster remove_node options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--remove strings[,...]
A comma-separated list of hosts to remove from the database.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--depot-path string
[Eon only] The absolute path to depot directory.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

To remove the nodes at 192.0.2.0 and 192.0.2.1:

$ vcluster remove_node --db-name vertica_db \
  --remove 192.0.2.0,192.0.2.1 \

1.2.13 - remove_sucluster

Removes a non-sandboxed subcluster and its nodes from an Eon Mode database.

Removes a non-sandboxed subcluster and its nodes from an Eon Mode database.

Syntax

vcluster remove_subcluster options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string
Name of subcluster to remove.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--data-path string
The absolute path to the data directory. This should be the same for all nodes in the database.
--depot-path string
[Eon only] The absolute path to depot directory.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

To remove the subcluster sc1:

$ vcluster remove_subcluster --subcluster sc1 \
  --config /opt/vertica/config/vertica_cluster.yaml

1.2.14 - return_epoch

Returns the last good epoch.

Returns the last good epoch.

Syntax

vcluster return_epoch options

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--catalog-path string
The absolute path to the catalog directory.
--cert-file string
The path to the certificate file.

Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--db-user string
The username for connecting to the database.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To return the last good epoch:

vcluster return_epoch

1.2.15 - revive_db

Revives or restores an Eon Mode database. You cannot revive sandboxes with this command.

Revives or restores an Eon Mode database. You cannot revive sandboxes with this command.

Syntax

vcluster revive_db options

Required options

If access to communal storage requires access keys, you must provide the keys with the --config-param option.

--communal-storage-location string
[Eon only] The absolute path of your communal storage location.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--hosts strings
Comma-separated list of hosts in the database. The number of hosts that you provide must match the number of hosts in the existing database. You can omit the hosts only if --display-only is specified.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

{ -c | --config } string
The path to write the configuration file.

Default: /opt/vertica/config/vertica_cluster.yaml

.

--config-param PARAMETER=VALUE[,...]
A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:
  • AWSAuth
  • AWSEndpoint
  • AWSEnableHttps
  • AWSRegion
--display-only
Shows information about the database in communal storage. If you specify this option, you can omit --hosts.
--force-removal
Deletes any existing database directories before reviving, excluding user storage directories.
{ -h | --help }
Prints help text.
--ignore-cluster-lease
Do not check for the existence of other clusters running on shared storage. If another system is using the same communal storage, using this option results in data corruption.

Default: Disabled

--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--load-catalog-timeout uint
The timeout, in seconds, for loading the remote catalog.

Default: 3600

{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string
Writes the output to the specified file instead of STDOUT.

Default: STDOUT

--restore-point-archive string
The name of the restore point archive to use for bootstrapping. If you specify this option, you must also specify --restore-point-id or -restore-point-index.
--restore-point-id string
The identifier of the restore point in the restore archive.
--restore-point-index int
The index of the restore point in the restore archive to restore from. Restore point indexes are one-indexed.
--verbose
Shows the details of VCluster run in the console.

Examples

To revive the database and write the configuration file to /opt/vertica/config/vertica_cluster.yaml:

$ vcluster revive_db --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --config /opt/vertica/config/vertica_cluster.yaml

To restore the database using the restore point archive db at index 1:

$ vcluster revive_db --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --config /opt/vertica/config/vertica_cluster.yaml --force-removal \
  --restore-point-archive db --restore-point-index 1

1.2.16 - sandbox_subcluster

Sandboxes a subcluster in an Eon Mode database.

Sandboxes a subcluster in an Eon Mode database. All hosts in the subcluster must be up. When you sandbox a subcluster, its hosts immediately shut down and restart; the subcluster becomes sandboxed after the hosts start back up.

A sandbox can contain multiple subclusters, and subclusters in the sandbox can interact with each other. If you want to isolate subclusters, they must be in separate sandboxes.

Syntax

vcluster sandbox_subcluster options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--sandbox string
The name of the sandbox. This string must conform to the format used for database names.
--subcluster string
The name of the subcluster to sandbox.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

To sandbox a subcluster sc1:

$ vcluster sandbox_subcluster --subcluster sc1 --sandbox sand \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 --db-name test_db

1.2.17 - scrutinize

Runs the scrutinize utility to collect diagnostic information about a database.

Runs the scrutinize utility to collect diagnostic information about a database. The cusotmer support team might request you to run this utility when resolving a case.

By default, diagnostics are stored in a /tmp/scrutinize/VerticaScrutinize.timestamp.tar.

For details, see Running scrutinize.

Syntax

vcluster scrutinize options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--db-user string
The username of a database user.
--exclude-active-queries
Exclude information affected by currently running queries.
--exclude-containers
Excludes information in system tables that can scale with the number of ROS containers.
{ -h | --help }
Prints help text.
--include-external-table-details
Include information about external tables. This option is computationally expensive.
--include-ros
Include information about ROS containers.
--include-udx-details
Include information describing all UDX functions. This option can be computationally expensive for Eon Mode databases.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--log-age-hours int
The maximum age, in hours, of archived database log files to collect.

Default: 24

--log-age-newest-time YYYY-MM-DD HH [+|-XX]
Timestamp of the minimum age of archived database log files to collect with an optional UTC hour offset [+|-XX].
--log-age-oldest-time YYYY-MM-DD HH [+|-XX]
Timestamp of the maximum age of archived database log files to collect with an optional UTC hour offset [+/-XX].
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--skip-collect-libraries
Skips gathering linked and catalog-shared libraries.
--tarball-name string
Name of the generated .tar.

Default: VerticaScrutinize.timestamp.tar

--verbose
Shows the details of VCluster run in the console.

Examples

Runs scrutinize on all nodes in the database:

$ vcluster scrutinize --db-name vertica_db --db-user dbadmin \
  --password testpassword --config /opt/vertica/config/vertica_cluster.yaml

1.2.18 - show_restore_points

Shows restore points.

Shows restore points.

Syntax

vcluster show_restore_points options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--communal-storage-location string
[Eon only] The absolute path of your communal storage location.
--config-param PARAMETER=VALUE[,...]
A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:
  • AWSAuth
  • AWSEndpoint
  • AWSEnableHttps
  • AWSRegion
--end-timestamp string
Shows restore points up to and including the specified UTC timestamp in either date-time or date-only format. For example:
  • "2006-01-02 15:04:05"
  • "2006-01-02"
  • "2006-01-02 15:04:05.000000000"
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--restore-point-archive string
Filter for restore point names that include the specified string.
--restore-point-id string
Filter for restore point IDs that include the specified ID.
--restore-point-index string
Filter for restore points indices that include the specified index.
--start-timestamp string
Shows restore points after and including the specified UTC timestamp in either date-time or date-only format. For example:
  • "2006-01-02 15:04:05"
  • "2006-01-02"
  • "2006-01-02 15:04:05.000000000"
--verbose
Shows the details of VCluster run in the console.

Examples

Show all restore points:

$ vcluster show_restore_points --db-name vertica_db \
  --config /opt/vertica/config/vertica_cluster.yaml

Show all restore points on an Eon Mode database:

$ vcluster show_restore_points --db-name vertica_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal

Show restore points with the name db1:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --restore-point-archive db1

Show restore points on an Eon Mode database with the ID 34668031-c63d-4f3b-ba97-70223c4f97d6:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --restore-point-id 34668031-c63d-4f3b-ba97-70223c4f97d6

Show restore points on an Eon Mode database between 2024-03-04 08:32:33.277569 and 2024-03-04 08:32:34.176391:

$ vcluster show_restore_points --db-name test_db \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
  --communal-storage-location /communal \
  --start-timestamp 2024-03-04 08:32:33.277569 \
  --end-timestamp 2024-03-04 08:32:34.176391

1.2.19 - start_db

Starts a database and establishes cluster quorum.

Starts a database and establishes cluster quorum.

The IP address provided for each node name must match the current IP address in the OpenText™ Analytics Database catalog. If the IPs do not match, you must first run re_ip to inform the database of the updated IP addresses.

If you pass the --hosts option a subset of all nodes in the cluster, only the specified nodes are started, and the specified subset must be a quorum of nodes.

Syntax

vcluster start_db options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--catalog-path string
The absolute path to the catalog directory.
--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--communal-storage-location string
[Eon only] The absolute path of your communal storage location.
--config-param PARAMETER=VALUE[,...]
A comma-separated list of PARAMETER=VALUE pairs. Parameters specified with this option override the ones in configuration files, if any, and take the following parameters:
  • AWSAuth
  • AWSEndpoint
  • AWSEnableHttps
  • AWSRegion
--config-param-file string
The absolute path to a file containing configuration parameters and their values.
--eon-mode
[Eon only] Indicates that the database is an Eon Mode database.
--epoch string
[Enterprise only] Specifies the epoch from which the database should start. If --epoch last is provided, the database starts from the last known good epoch.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--main-cluster-only
Starts the database on a main cluster and does not start any sandboxes.
{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--sandbox string
Name of the sandbox to start.
--sync-catalog
Whether to sync the catalog after all nodes are up.
--timeout int
The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).

Default: 300

--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To start a database

$ vcluster start_db --password my_password \
  --config /opt/vertica/config/vertica_cluster.yaml

To start a datbase from the last good epoch:

Return the last good epoch:

vcluster return_epoch

Start from the last good epoch:

vcluster start_db --epoch 1234

1.2.20 - start_node

Starts nodes in a running cluster.

Starts nodes in a running cluster. This differs from start_db, which starts OpenText™ Analytics Database after cluster quorum is lost.

Syntax

vcluster restart_node options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

One of --restart and --start-hosts is required.

--restart node_name=ip_address[,...]
A comma-separated list of node_name=ip_address pairs, specifying the nodes to restart. If ip_address doesn't match the database's listed IP address for that node, OpenText™ Analytics Database updates its catalog information for that node with the specified IP address and then restarts the node.
--start-hosts string[,...]
A comma-separated list of hosts to be restarted.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--timeout int
The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).

Default: 300

--verbose
Shows the details of VCluster run in the console.

Examples

To restart a node:

$ vcluster restart_node --db-name vertica_db \
    --restart v_vertica_db_node0004=192.0.2.0 --password my_password \
    --config /opt/vertica/config/vertica_cluster.yaml

To restart a single node and change its IP address in the database with config file (assuming the node IP address previously stored catalog was not 192.0.2.4):

$ vcluster restart_node --db-name vertica_db \
  --restart v_vertica_db_node0004=192.0.2.4 --password testpassword \
  --config /opt/vertica/config/vertica_cluster.yaml

To restart multiple nodes:

$   vcluster restart_node --db-name test_db \
  --restart v_test_db_node0003=192.0.2.3,v_test_db_node0004=192.0.2.4 \
  --password testpassword --config /opt/vertica/config/vertica_cluster.yaml

1.2.21 - start_subcluster

Starts stopped nodes in a subcluster.

Starts stopped nodes in a subcluster.

Syntax

vcluster start_subcluster options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string
Name of subcluster to start

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--timeout int
The time (in seconds) to wait for nodes to start up. Extend this value to allow additional time (for example, 3600 for one hour).

Default: 300

--verbose
Shows the details of VCluster run in the console.

Examples

To start a subcluster:

$ vcluster start_subcluster --subcluster sc1 \
  --config /opt/vertica/config/vertica_cluster.yaml

1.2.22 - stop_db

Stops a database or sandbox.

Stops a database or sandbox.

Syntax

vcluster stop_db options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--drain-seconds int
[Eon only] The time to wait, in seconds, for user connections to close on their own. When the time expires, user connections are automatically closed and the database is shut down. If set to 0, VCluster closes all user connections immediately. If the value is negative, VCluster waits indefinitely until all user connections close.

Default: 60

--eon-mode
[Eon only] Indicates that the database is an Eon Mode database.
--force-kill
Closes all active sessions before stopping the database.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--if-no-users
Shuts down the database only if no users are currently connected. If any users are connected, the command exits with an error.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

--main-cluster-only
Stops the database without stopping any sandboxed subclusters.
{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--sandbox string
Name of the sandbox to stop.
--sync-catalog
Specifies whether to sync the catalog before stopping the database.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To stop a database with default drain timeout (60 seconds):

vcluster stop_db

To stop a database with config file using password authentication with user-specified drain seconds:

  vcluster stop_db --password "PASSWORD" \
    --config /opt/vertica/config/vertica_cluster.yaml --drain-seconds 10

To stop a database if no users are connected:

vcluster stop_db --if-no-users

To close all active sessions before stopping the database:

vcluster stop_db --force-kill

To stop a database with config file using password authentication and close all active sessions before stopping the database:

  vcluster stop_db --password "PASSWORD" \
    --config /opt/vertica/config/vertica_cluster.yaml
    --force-kill

1.2.23 - stop_node

Stops one or more nodes in a database.

Stops one or more nodes in a database.

You must provide the host list with the --stop-hosts option followed by one or more hosts to stop as a comma-separated list.

Syntax

vcluster stop_node options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--stop-hosts string
Comma-separated list of host(s) to stop.

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
--force-kill
Forces node termination using SIGKILL instead of a graceful shutdown (SIGTERM).
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

Stop the node on 192.0.2.0 and 192.0.2.1:

$ vcluster stop_node --stop-hosts 192.0.2.0,192.0.2.1 \
  --config /home/dbadmin/vertica_cluster.yaml

1.2.24 - stop_subcluster

Stops a subcluster and all its hosts.

Stops a subcluster and all its hosts.

Syntax

vcluster stop_subcluster options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string
The name of the subcluster to stop.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--drain-seconds int
[Eon only] The time to wait, in seconds, for user connections to close on their own. When the time expires, user connections are automatically closed and the database is shut down. If set to 0, VCluster closes all user connections immediately. If the value is negative, VCluster waits indefinitely until all user connections close.

Default: 60

--force
Shut down the subcluster immediately even if users are connected.
{ -h | --help }
Prints help text.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

Stops the subcluster sc1, waiting 10 seconds for user connections to close:

$ vcluster stop_subcluster --subcluster sc1 --drain-seconds 10 \
  --config /opt/vertica/config/vertica_cluster.yaml

1.2.25 - uninstall_packages

Uninstalls the packages from /opt/vertica/packages.

Uninstalls packages from /opt/vertica/packages to remove unused or problematic packages, clean up before reinstalling, or reduce database size.

Syntax

vcluster uninstall_packages options

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The path to the certificate file.

Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -o | --output-file } string
Writes the output to the specified file instead of STDOUT.

Default: STDOUT

--package string
Select packages using all, default, specific package name, or comma-separated list of package names.

Default: all

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To uninstall all available packages (default):

vcluster uninstall_packages

To uninstall default packages:

vcluster uninstall_packages --package "default"

To uninstall all packages:

vcluster uninstall_packages --package "all"

To uninstall a specific package:

vcluster uninstall_packages --package "ComplexTypes"

To uninstall multiple packages (comma-separated):

vcluster uninstall_packages --package "ComplexTypes,kafka,logsearch"

To uninstall all packages using database and host name:

vcluster uninstall_packages --db-name test_db \
    --hosts 192.0.2.0,192.0.2.1,192.0.2.2 \
    --password <PASSWORD>

1.2.26 - unsandbox_subcluster

Removes a subcluster from the sandbox, unsandboxing it.

Removes a subcluster from the sandbox, "unsandboxing" it. When you unsandbox a subcluster, its hosts immediately shut down and restart. When the hosts come back up, the subcluster is unsandboxed.

When a subcluster is unsandboxed, you should manually delete that subcluster's metadata in communal storage before attempting to add a subcluster to that sandbox again. For example, if you unsandbox subcluster sc1, you should delete the directory path_to_catalog_of_sc1/metadata/sandbox_name.

Syntax

$ vcluster unsandbox_subcluster options

Required options

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

--subcluster string
The name of the subcluster to be unsandboxed.

Options

--cert-file string
The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database. This must include at least one up host from the primary subcluster.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--verbose
Shows the details of VCluster run in the console.

Examples

To unsandbox subcluster sc1:

$ vcluster unsandbox_subcluster --subcluster sc1 \
  --hosts 192.0.2.0,192.0.2.1,192.0.2.2 --db-name vertica_db

1.2.27 - upgrade_license

Upgrades license

Upgrades the database license by applying a new license file to an existing database or replacing an expired license.

Syntax

vcluster upgrade_license options

Required options

--license-file string
Absolute path of the license file.

Options

--ca-cert-file string
The path to the trusted CA certificate file.

Default: /opt/vertica/config/https_certs/rootca.pem

--cert-file string
The path to the certificate file.

Default: /opt/vertica/config/https_certs/{username}.pem

{ -c | --config } string
The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.

Default: /opt/vertica/config/vertica_cluster.yaml

{ -d | --db-name } string
The name of the database. You should only use this option if you want to override the database name in your configuration file. This string must conform to the format used for database names.
{ -h | --help }
Prints help text.
--hosts strings
A comma-separated list of hosts in the database.
--ipv6
Specifies if the hosts use IPv6 addresses.

Default: IPv4

--key-file string
Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.
--license-host string
The host where the license file is located.
{ -l | --log-path } string
The absolute path for debug logs.

Default: /opt/vertica/log/vcluster.log

{ -p | --password } string
The database password.
--password-file string
The absolute path to a file containing the database password.

If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

--read-password-from-prompt
Prompts the user to enter the password.
--tls-mode string
Sets the TLS validation mode. Valid options are enable, verify-ca, verify-full.

Default: enable

--use-password-for-sql-client-only
Use the password for the NMA SQL client only.
--verbose
Shows the details of VCluster run in the console.

Examples

To upgrade a license:

vcluster upgrade_license --license-file LICENSE_FILE --license-host HOST_OF_LICENSE_FILE

To upgrade a license using the database password:

vcluster upgrade_license --license-file LICENSE_FILE --license-host HOST_OF_LICENSE_FILE  --password "PASSWORD"

2 - Database management with VCluster UI

Database management with VCluster UI

The VCluster UI is a tool for administering a single database. This tool is bundled with OpenText™ Analytics Database installations. VCluster UI works with the VCluster CLI to manage your database. It works with both the EON and Enterprise database types.

Setting up VCluster UI

Setting up the VCluster UI for your system depends on whether you already have a database set up and how you created your database: AdminTools or VCluster CLI. Use the section below that corresponds to your setup:

Configure VCluster server

To setup VCluster UI and create a new database:

  1. Start the node management agent on all of the nodes:

    $  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

    Here is an example script that can be used to start the node management agent on multiple nodes:

    for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

  2. Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):

    $  /opt/vertica/bin/manage_vcluster_server.sh start vluster_server

    This will create a certificate for the UI that you need to import into your browser.

  3. Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.

  4. In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.

  5. Launch the VCluster Web UI by navigating to https://<hostname>:8665. When prompted, select the certificate that you just imported and click OK.

  6. Click the link in the Dashboard to create your database.

VCluster UI create database

Create a database from VCluster UI

  1. After you click the link to create a database, you are directed to the Create Database page.
  2. Choose Eon or Enterprise as the database type. The available fields change based on your selection.
  3. Specify the details of your database.
  4. Click Create.
  5. In the Job Satus page, you can view the status of your new database.
  6. Continue with Accessing the VCluster UI.

Access existing database from VCluster UI

Follow these steps if your database was created using the VCluster CLI:

  1. Start the node management agent on all of the nodes:

    $  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

    Here is an example script that can be used to start the node management agent on multiple nodes:

    for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

  2. Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):

    $  /opt/vertica/bin/manage_vcluster_server.sh start vluster_server

    This will create a certificate for the UI that you need to import into your browser.

  3. Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.

  4. In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.

  5. Launch the VCluster Web UI by navigating to https://<hostname>:9090. When prompted, select the certificate that you just imported and click OK.

  6. The VCluster Web Server leverages an embedded HTTPS service, which requires TLS authentication for secure access. Run the following to enable TLS:

    vsql -c "create authentication tls_for_all method 'tls' host tls '0.0.0.0/0';" 
vsql -c "grant authentication tls_for_all to public;"

  7. Continue with Accessing the VCluster UI.

Migrate your database from AdminTools to VCluster UI

Follow these steps if your database was created using AdminTools:

  1. Start the node management agent on all of the nodes:

    $  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

    Here is an example script that can be used to start the node management agent on multiple nodes:

    for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

  2. Run the following script to convert the database configuration to be compatible with VCluster:

    /opt/vertica/bin/vcluster manage_config recover --db-name migrate_to_vcluster --hosts <list of node IP address separated by commas> --catalog-path /scratch_b/disk_a  --depot-path /scratch_b/disk_a

  3. Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):

    $  /opt/vertica/bin/manage_vcluster_server.sh start vluster_server

    This will create a certificate for the UI that you need to import into your browser.

  4. Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.

  5. In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.

  6. Launch the VCluster Web UI by navigating to https://<hostname>:9090. When prompted, select the certificate that you just imported and click OK.

  7. Continue with Accessing the VCluster UI.

Access VCluster UI

To access VCluster UI, navigate to https://<hostname>:8665 using the server IP of the database host where you started the VCluster service. You are prompted to select the server certificate you imported to your browser previously.

Understanding VCluster UI

VCluster UI dashboard

  • OpenText™ Analytics Database version information: Displays the current version of the database.

  • Help: Access the VCluster UI documentation and swagger documentation.

  • Left navigation: Shows the available pages and highlights the current page.

  • Landing page: Displays the different tiles to manage your database.

2.1 - Dashboard

VCluster UI Dashboard page

The VCluster UI Dashboard is the default landing page of the interface. It provides quick access to health metrics and other key sections allowing you to navigate and manage your database efficiently.

VCluster UI dashboard

Access Health Metrics

  1. Click Health Metrics. The Connect Vcluster to Prometheus modal appears.

  2. Provide OpenText™ Analytics Database's embedded HTTPS server port number and click Start Prometheus. The default is 8443.

  3. Click Accept to authorize the Prometheus connection.

  4. Click Confirm. VCluster is now connected to Prometheus to scrape metrics.

    You will be directed to the Dashboard which displays health metrics such as CPU Usage by Node, Memory Usage by Node, Disk I/O Usage by Node, and Free Disk Space by Node. Click any chart to open a modal where you can filter by time and node.

  5. You can set the Refresh Interval to automatically update the health charts at your preferred frequency.

  6. Click Other Health Data to access Health Watchdog and Cluster Health pages.

  7. Clicking Health Metrics keeps the dashboard in health metrics view during your browser session. To go back to the default dashboard, click Stop Health Metrics and then click Confirm.

VCluster UI dashboard metrics

2.2 - Subcluster

VCluster UI Subcluster page

The VCluster UI Subcluster page displays a list of your subclusters and the number of nodes in each subcluster. You can also add, remove, start, stop, sandbox, and unsandbox subclusters.

VCluster UI subcluster page

Node Details for a subcluster enables you to view the node name, address, state, catalog path, and primary node.

2.3 - Database

VCluster UI Database page

The Database page shows you the name of your database along with the nodes, IP Address, and status. You can also view more details for each node such as node name, catalog path, data path, depot path, and communal storage location.

VCluster UI database page

The following options are available on this page:

  • Start Database

  • Stop Database

  • Re-IP Database

  • Drop Database

  • Revive Database: You will not see this option if a database already exists.

  • Additional Options: Include Upgrade License and Manage Packages.

    • The Upgrade License option enables you to choose your license file and upgrade to it.

    • The Manage Packages option enables you to install or uninstall pacakges. It lists all the packages that are installed or uninstalled. You will be directed to the Job Status page when you install or uninstall packages.

2.4 - Nodes

VCluster UI Nodes page

The Nodes page shows you all of your database nodes. You can add, remove, start, and stop nodes on this page.

VCluster UI nodes page

2.5 - Job Status

VCluster UI Job Status page

The Job Status page shows you the status of your database jobs and the Workload Replay captures and replays:

Database

VCluster UI job status database page

Database shows you the status of jobs from the Database, SubCluster, and Nodes pages. This includes adding a node or subcluster, changing the IP of the database, creating the database, and the other options.

Workload Replay

VCluster UI job status workload replay page

2.6 - Workload Replay

VCluster UI Workload Replay page

The Workload Replay page lets you view your database workload by viewing database queries and how long they take.

VCluster UI workload replay page

This page is used for the following:

  • Evaluating the performance of a new database version before deploying it to the production environment.

  • Assessing changes to the system configuration or test the database with new knobs or code changes.

  • Assessing the performance of upgrading hardware components or switching to a different operating system.

It uses three tabs to help you perform the assessment: Capture Workload, Replay Workload, and Reports.

Capture

VCluster UI workload replay capture

Capture is used to capture a query or multiple queries to see their performance. You specify a start and stop timestamp when the query/queries you want to capture were run. Then click Capture Worload to capture the query/queries. You are redirected to the Job Status > Workload Replay page to see the status of the capture. The job name will be capture-workload and once the status shows successful you can replay the workload. You need to note the file path for the capture job to run the replay.

Replay Workload

VCluster UI workload replay workload

After running a capture, Replay Workload is used to compare the first query run time with a new query run time. Select a sandbox from the dropdown to use for the replay. If no sandbox is present in the dropdown, you can create a sandbox using Create sandbox. You need to know the file path from the Job Status > Workload Replay page to select the capture you want to run against. Select that in the Workload File drop down. In the Sandbox drop down, select the sandbox you are using for the replay, then click Replay Workload. You are redirected to the Job Status > Workload Replay page to see the status of the capture.

VCluster UI job status workload replay

The job name will be replay-workload and once the status shows successful you can replay the workload. You need to note the file path for the replay job to run the report.

If you want to cancel the replay that is running, hit the Cancel Replay Workload button.

Reports

VCluster UI workload replay reports

After running the replay, Reports lets you view the query/queries from both the capture and the replay side by side. In the Workload Replay Report File, make sure the replay file you want to view is selected. It can be found on the Job Status > Workload Replay page. You can see a chart of the original time and the replay time which can be customized to how you want to view it. Scrolling down also shows you a table of the results.

2.7 - Cluster Health

VCluster UI Cluster Health page

The Cluster Health page lets you monitor the health of your database. There are three sections on this page:

  • Event Detailed Info - displays the details of an event if you click on it in the Slow Event Duration Over Time chart. You can click on the event details to see additional details about the event.

  • Events Statistics - displays the number of slow events, the longest and average event time, and lets you run a manual slow event check over a specified time period.

  • Slow Event Duration Over Time - displays the events from the preview day, 7 days, or 30 days (per your selection) in a chart.

VCluster UI healh page

2.8 - Health Watchdog

VCluster UI Health Watchdog page

The Health Watchdog page lets you monitor your database using Health Watchdog. It displays the health of your database and mergeout queue size, lets you set configuration parameters for your database, and view blocked transactions.

Database Status

VCluster UI health watchdog database status

The Database Status page shows you your cluster state and has charts to track the different health metrics. You can set the chart to display recently elapsed time window or for a fixed time range.

Configuration Parameters

VCluster UI health watchdog configuration parameters

The Configuration Parameters page lets you configure the health metrics for your database. It displays the current value for the health metric and lets you input new values if you need to adjust your settings. You can also select whether transactions are blocked or not.

Blocked Transactions

VCluster UI health watchdog blocked transactions

The Blocked Transactions page lets you view any transactions that have been blocked and lets you cancel any transactions that you select.

2.9 - Certificate Management

VCluster UI Job Status page

The Certificate Management page shows you your certificate information and manage your certificates.

VCluster UI certificate management page

The following options are available to manage certificates:

  • Pending Certs list: Shows a list of the status of server and client certificates.

VCluster UI certificate management pending certificates

  • Issued Certs list: Shows a list of the issued certficates.

VCluster UI certificate management issue certificates

  • Revoked Certs list: Shows a list of the revoked certificates.

VCluster UI certificate management revoked certificates

  • Renew Server Cert: Lets you renew your server certificate.

VCluster UI certificate management renew certificates

  • Apply Client Cert: Use this option to apply for a client certificate.

VCluster UI certificate managment apply client certificate