Backup Location

Description

The px pxb backuplocation commands manage backup locations used to store backups. A backup location can be an S3-compatible object store, Azure Blob Storage, Google Cloud Storage, or an on-premises NFS path. You can create, validate, update, list, delete, and manage ownership of backup locations.

Usage

Create Backup Location

px pxb create backuplocation --name <location-name> \
  --provider <s3|azure|google|nfs> --path <bucket-or-path> [flags]

Get Backup Location (Inspect)

px pxb get backuplocation --name <location-name> [--uid <uid>] [flags]

Get Backup Location (List All)

px pxb get backuplocation [flags]

Update Backup Location

px pxb update backuplocation --name <location-name> [--uid <uid>] [flags]

Delete Backup Location

px pxb delete backuplocation --name <location-name> [--uid <uid>] [flags]

Validate Backup Location

px pxb validate backuplocation --name <location-name> [--uid <uid>] [flags]

Update Ownership (Access Control)

px pxb update ownership backuplocation --name <location-name> [--uid <uid>] [flags]

Examples

Create S3 Backup Location

px pxb create backuplocation \
  --name s3-primary \
  --provider s3 \
  --path px-backups/app \
  --cloud-credential-name aws-cred \
  --s3-endpoint s3.amazonaws.com \
  --s3-region us-east-1

Create S3 with encryption and object lock

px pxb create backuplocation \
  --name encrypted-s3 \
  --provider s3 \
  --path secure-bucket/px \
  --cloud-credential-name aws-cred \
  --s3-endpoint s3.amazonaws.com \
  --s3-region us-west-2 \
  --s3-sse SSE-KMS \
  --encryption-key myKmsKeyAlias \
  --object-lock-enabled

Create GCS Backup Location

px pxb create backuplocation \
  --name gcs-backups \
  --provider google \
  --path gcs-bucket/backups \
  --cloud-credential-name gcp-cred

Create Azure Blob Backup Location

# Basic Azure backup location (defaults to AZURE_GLOBAL environment)
px pxb create backuplocation \
  --name azure-backups \
  --provider azure \
  --path container-name-prefix \
  --cloud-credential-name azure-cred

# Azure backup location with explicit global environment
px pxb create backuplocation \
  --name azure-global \
  --provider azure \
  --path container-name-global-backups \
  --cloud-credential-name azure-cred \
  --azure-environment AZURE_GLOBAL

# Azure backup location for China environment
px pxb create backuplocation \
  --name azure-china \
  --provider azure \
  --path container-name-china-backups \
  --cloud-credential-name azure-china-cred \
  --azure-environment AZURE_CHINA

# Azure backup location with resource group (for immutable buckets)
px pxb create backuplocation \
  --name azure-immutable \
  --provider azure \
  --path container-name-immutable-backups \
  --cloud-credential-name azure-cred \
  --azure-environment AZURE_GLOBAL \
  --azure-resource-group my-backup-resource-group

Create NFS Backup Location

px pxb create backuplocation \
  --name nfs-archive \
  --provider nfs \
  --path /exports/backups \
  --nfs-server-addr 10.0.0.10 \
  --nfs-mount-options "vers=4,rsize=1048576"

Validate and List

px pxb validate backuplocation --name s3-primary
px pxb get backuplocation --output json

# List all backup locations
px pxb get backuplocation

# Filter by cloud credential
px pxb get backuplocation --cloud-credential-name aws-cred --include-secrets

# Exclude validation state and filter by labels
px pxb get backuplocation --include-validation-state=false --labels-file /path/to/labels.json

Note: By default, px pxb get backuplocation shows ALL backup locations including those in ValidationInProgress and ValidationFailed states. Use --include-validation-state=false to hide NFS backup locations that are currently being validated or have failed validation.

Update Cloud Credential or Settings

px pxb update backuplocation --name s3-primary --cloud-credential-name aws-cred-rotated
px pxb update backuplocation --name s3-primary --validate-cloud-credential=false
px pxb update backuplocation --name s3-primary --provider s3 --s3-endpoint new-endpoint --s3-region eu-west-1

# Update Azure configuration
px pxb update backuplocation --name azure-backups --provider azure --azure-environment AZURE_CHINA --cloud-credential-name azure-cred
px pxb update backuplocation --name azure-backups --provider azure --azure-resource-group new-resource-group --cloud-credential-name azure-cred
px pxb update backuplocation --name azure-backups --provider azure --azure-environment AZURE_GLOBAL --azure-resource-group prod-rg --cloud-credential-name azure-cred

# Update NFS configuration
px pxb update backuplocation --name nfs-archive --provider nfs --nfs-server-addr 10.0.0.20 --nfs-sub-path production/backups --nfs-mount-options "vers=4,rsize=2097152"

Delete

px pxb delete backuplocation --name s3-primary

Update Ownership

# Add groups with access levels
px pxb update ownership backuplocation --name s3-primary \
  --add-groups "devops=Admin,ops=Write"

# Add collaborators
px pxb update ownership backuplocation --name s3-primary \
  --add-collaborators "alice-user-123=Read"

# From file (CLI flags override file)
px pxb update ownership backuplocation --name s3-primary \
  --file /path/to/backuplocation-ownership.json

Ownership file examples

Complete ownership request (backuplocation-ownership.json):

{
  "name": "s3-primary",
  "ownership": {
    "groups": [
      { "id": "devops", "access": "Admin" },
      { "id": "ops", "access": "Write" }
    ],
    "collaborators": [
      { "id": "alice-user-123", "access": "Read" }
    ],
    "public": { "type": "Read" }
  }
}

Granular files:

// groups.json
{
  "devops": "Admin",
  "ops": "Write"
}

// collaborators.json
{
  "alice-user-123": "Read"
}

Flags for commands and sub-commands

Create Backup Location Flags

Required Flags (optional with --file)

Flag	Short	Type	Description
--name	-n	string	Name of the backup location (required, optional with --file)
--provider	-p	string	Storage provider: s3, azure, google, nfs (required, optional with --file)
--path		string	Storage path (bucket/prefix for cloud; directory for NFS) (required, optional with --file)

Common Options

Flag	Short	Type	Description
--cloud-credential-name		string	Name of cloud credential to use
--cloud-credential-uid		string	UID of cloud credential to use
--validate-cloud-credential		bool	Validate cloud credential before creating (default: true)
--encryption-key		string	Encryption key for backup data
--object-lock-enabled		bool	Enable object lock for immutable backups (S3 only)
--file	-f	string	YAML/JSON file containing complete backup location configuration
--s3-config-file		string	YAML/JSON file containing S3-specific configuration
--nfs-config-file		string	YAML/JSON file containing NFS-specific configuration

S3 Options

Flag	Short	Type	Description
--s3-endpoint		string	S3 endpoint URL (e.g., s3.amazonaws.com)
--s3-region		string	S3 region (e.g., us-west-2)
--s3-sse		string	S3 server-side encryption: SSE-S3 or SSE-KMS
--s3-disable-ssl		bool	Disable SSL for S3 connections
--s3-disable-path-style		bool	Disable path-style addressing for S3

Azure Options

Flag	Short	Type	Description
--azure-environment		string	Azure environment: AZURE_GLOBAL, AZURE_CHINA (default: AZURE_GLOBAL)
--azure-resource-group		string	Azure resource group name (optional, for immutable buckets)

NFS Options

Flag	Short	Type	Description
--nfs-server-addr		string	NFS server address (IP or hostname)
--nfs-sub-path		string	Subdirectory under NFS export path
--nfs-mount-options		string	NFS mount options (e.g., "vers=4,rsize=1048576")

Get Backup Location Flags

Inspect (optional with --file)

Flag	Short	Type	Description
--name		string	Name to inspect (optional with --file, required for inspect mode otherwise)
--uid		string	UID of the location (optional; use with --name to disambiguate)

Enumerate Filters

Flag	Short	Type	Description
--cloud-credential-name		string	Filter by cloud credential name
--cloud-credential-uid		string	Filter by cloud credential UID
--include-secrets		bool	Include secrets in the output
--include-validation-state	true	bool	Include backup locations in ValidationInProgress and ValidationFailed states (default: true)
--labels-file		string	Path to YAML/JSON file containing labels for filtering

File Input

Flag	Short	Type	Description
--file	-f	string	YAML/JSON file containing complete get configuration

Update Backup Location Flags

Identification

Flag	Short	Type	Description
--name	-n	string	Name of the location to update (required, optional with --file)
--uid		string	UID of the location to update (optional)

Cloud Credentials

Flag	Short	Type	Description
--cloud-credential-name		string	New cloud credential name
--cloud-credential-uid		string	New cloud credential UID
--validate-cloud-credential		bool	Validate cloud credential (default: true)

Provider Configuration

Flag	Short	Type	Description
--provider	-p	string	Update storage provider configuration: s3, azure, google, nfs

S3 Options

Flag	Short	Type	Description
--s3-endpoint		string	S3 endpoint URL
--s3-region		string	S3 region
--s3-disable-ssl		bool	Disable SSL for S3 connections
--s3-disable-path-style		bool	Disable path-style addressing for S3

NFS Options

Flag	Short	Type	Description
--nfs-server-addr		string	NFS server address
--nfs-sub-path		string	NFS subdirectory path
--nfs-mount-options		string	NFS mount options

File Input (granular)

Flag	Short	Type	Description
--s3-config-file		string	YAML/JSON file containing S3-specific configuration
--nfs-config-file		string	YAML/JSON file containing NFS-specific configuration

Delete Backup Location Flags

Flag	Short	Type	Description
--name		string	Name of the backup location to delete (required, optional with --file)
--uid		string	UID of the backup location (optional)

Validate Backup Location Flags

Flag	Short	Type	Description
--name		string	Name of the backup location (required, optional with --file)
--uid		string	UID of the backup location (optional)

Ownership Update Flags

Required Identification (optional with --file)

Flag	Short	Type	Description
--name	-n	string	Name of the backup location (optional with --file, required otherwise)
--uid		string	UID of the backup location (optional)

Ownership Management

Flag	Short	Type	Description
--add-groups		map	Add groups with access levels (group=Read|Write|Admin)
--add-collaborators		map	Add collaborators with access levels (user=Read|Write|Admin)
--public-access-control		string	Set public access control: Read, Write, or Admin

File Input

Flag	Short	Type	Description
--file	-f	string	YAML/JSON file containing complete ownership configuration
--add-groups-file		string	YAML/JSON file containing groups configuration
--add-collaborators-file		string	YAML/JSON file containing collaborators configuration

Azure Environment and Resource Group Details

Azure Environments

The --azure-environment flag specifies which Azure cloud environment to use:

• AZURE_GLOBAL (default): Azure public cloud environment used worldwide
• AZURE_CHINA: Azure China cloud environment operated by 21Vianet

If no environment is specified, AZURE_GLOBAL is used by default.

Azure Resource Groups

The --azure-resource-group flag is optional and serves several purposes:

• Immutable Storage: Required for Azure immutable storage containers to retrieve retention period information
• Resource Organization: Helps organize backup storage resources within Azure resource groups
• Compliance: May be required for certain compliance or governance requirements

Azure Configuration Examples

# Default global environment (no environment flag needed)
px pxb create backuplocation --name azure-default --provider azure --path container-backups --cloud-credential-name azure-creds

# Explicit global environment
px pxb create backuplocation --name azure-global --provider azure --path container-backups --cloud-credential-name azure-creds --azure-environment AZURE_GLOBAL

# China environment
px pxb create backuplocation --name azure-china --provider azure --path container-backups --cloud-credential-name azure-china-creds --azure-environment AZURE_CHINA

# With resource group for immutable storage
px pxb create backuplocation --name azure-immutable --provider azure --path container-backups --cloud-credential-name azure-creds --azure-environment AZURE_GLOBAL --azure-resource-group backup-rg

Notes

• Get semantics: Use --name to inspect a single backup location (UID optional); omit --name to enumerate all. Cloud credential filters apply only to enumeration.
• Required identification: For update, delete, validate, and ownership, --name is required; --uid is optional and used to disambiguate.
• File vs CLI precedence:
  • Create supports --file, --s3-config-file, and --nfs-config-file. CLI flags override values from files.
  • Note: When using --file on create, the required name may come from the file payload. If neither file nor CLI provides a name, the command fails validation.
  • Update supports granular provider files (--s3-config-file, --nfs-config-file); there is no top-level --file for update.
• Provider validation: Provider-specific flags are validated only when the selected provider is specified.
• Azure environment validation: Only AZURE_GLOBAL and AZURE_CHINA are accepted values for --azure-environment.

Output Format Support

• --output table (default)
• --output json
• --output yaml
• --output name (for get)

Authentication and Context

• Organization ID from context
• Authentication token from context
• Labels for list filtering from context