Service operations using pxctl

This document provides details for using the service mode utilities accessible through the pxctl service command. First, let’s get a glimpse of the available subcommands:

pxctl service --help
   pxctl service - Service mode utilities

   pxctl service command [command options] [arguments...]

     audit, a        Audit the PX node
     call-home       Enable or disable the call home feature
     diags, d        creates a new tgz package with minimal essential diagnostic information.
     drive           Storage drive maintenance
     email           Email setting commands
     exit, e         Stop the PX daemon
     info, i         Show PX module version information
     kvdb, k         PX Kvdb operations
     maintenance, m  Maintenance mode operations
     node-wipe, nw   Wipes PX configuration data on this node
     pool            Storage pool maintenance

   --help, -h  show help

pxctl service audit

Audit the PX node

pxctl service audit
AuditID		Error	Message
kvdb-limits	none	KV limits audit not yet available

kvdb-response	none	KV response audit not yet available

pxctl service call-home

You can use this command to enable and disable the call home feature

pxctl service call-home --help
   pxctl service call-home - Enable or disable the call home feature

   pxctl service call-home [arguments...]
pxctl service call-home enable
Call home feature successfully enabled

pxctl service diags

When there is an operational failure, you can use pxctl service diags <name-of-px-container> to generate a complete diagnostics package. This package will be automatically uploaded to Portworx if --upload is specified. Additionally, the service package can be mailed to Portworx at The package will be available at /var/cores/diags.tgz inside the PX container.

pxctl service diags --help
   pxctl service diags - creates a new tgz package with minimal essential diagnostic information.

   pxctl service diags [command options] [arguments...]

   -l, --live                gets diags from running px
   -u, --upload              upload diags to cloud
   -p, --profile             only dump profile
   -a, --all                 creates a new tgz package with all the available diagnostic information.
   -c, --cluster             generate diags for all the nodes in the cluster.
   -f, --force               force overwrite existing diags.
   -o, --output string       output file name (default "/var/cores/diags.tar.gz")
       --dockerhost string   docker host daemon (default "unix:///var/run/docker.sock")
       --container string    PX container ID
   -n, --node string         generate diags for a specific remote node with the provided NodeIp or NodeID.
pxctl service diags --container px-enterprise
PX container name provided:  px-enterprise
INFO[0000] Connected to Docker daemon.  unix:///var/run/docker.sock
Getting diags files...
Generated diags: /tmp/diags.tar.gz

pxctl service info

Displays all Version info

pxctl service info
PX (OCI) Version:
PX (OCI) Build Version:  1d83ac2baeb27451222edcd543249dd2c2f941e4
PX Kernel Module Version:  72D3C244593F45167A6B49D

pxctl service kvdb

kvdb command is used for confguring kvdb

pxctl service kvdb --help
   pxctl service kvdb - PX Kvdb operations

   pxctl service kvdb [command options] [arguments...]

   endpoints    List the kvdb client endpoints
   members      List the kvdb cluster members
   restore      Restore keys and values into kvdb from a kvdb.dump file

pxctl service maintenance

Use the service maintenance command to enter or exit maintenance mode. Once the node is in maintenance mode, you can add or replace drives, add memory, and so on.

To list the available subcommands, run the following:

pxctl service maintenance --help
   pxctl service maintenance - Maintenance mode operations

   pxctl service maintenance [command options] [arguments...]

   -x, --exit   exit maintenance mode
   -e, --enter  enter maintenance mode
   -c, --cycle  cycle maintenance mode

Enter maintenance mode with:

pxctl service maintenance --enter
This is a disruptive operation, PX will restart in maintenance mode.
Are you sure you want to proceed ? (Y/N): y

Exit maintenance mode by running:

pxctl service maintenance --exit

pxctl service drive

You can manage the physical storage drives on a node using the pxctl service drive sub menu.

pxctl service drive
   pxctl service drive - Storage drive maintenance

   pxctl service drive command [command options] [arguments...]

     add            Add storage
     check          Check drives
     rebalance      Rebalance storage
     replace        Replace source drive with target drive
     show           Show drives

   --help, -h  show help

You can add drives to a server using the /opt/pwx/bin/pxctl service drive add command. To do so the server must be in maintenance mode.

pxctl service drive add --help
   pxctl service drive add - Add storage

   pxctl service drive add [arguments...]
pxctl service drive add --drive /dev/mapper/volume-3bfa72dd -o start
Adding device  /dev/mapper/volume-3bfa72dd ...
Drive add  successful. Requires restart (Exit maintenance mode).

To rebalance the storage across the drives, use pxctl service drive rebalance. This is useful after prolonged operation of a node.

pxctl service drive show

You can use pxctl service drive show to display drive information on the server

pxctl service drive show
PX drive configuration:
Pool ID: 0
	IO_Priority: LOW
	Size: 100 GiB
	Status: Online
	Has meta data: Yes
	1: /dev/mapper/volume-e85a42ca, 1.0 GiB allocated of 100 GiB, Online

pxctl service email

Email setting commands

pxctl service email
   pxctl service email

   pxctl service email command [command options] [arguments...]

     clear     Clear email settings for alerts.
     set       Configure email settings for alerts.

pxctl service scan

You can use pxctl service scan to scan for bad blocks on a drive

pxctl service scan
   pxctl service scan - scan for bad blocks

   pxctl service scan command [command options] [arguments...]

     cancel    cancel running scan
     pause     pause running scan
     resume    resume paused scan
     schedule  examine or set schedule
     start     start scan
     status    scan status

pxctl service node-wipe

pxctl service node-wipe deletes all data related to Portworx from the node. It will also wipe the storage device that was provided to Portworx. This command can be run only when Portworx is stopped on the node. Run this command if a node needs to be re-initialized.

Note: This is a disruptive command and could lead to data loss. Please use caution.
pxctl service node-wipe --help
   pxctl service node-wipe - Wipes PX configuration data on this node

   pxctl service node-wipe [command options] [arguments...]

   --storage_devices value, -s value  comma-separated list of storage devices to be wiped.

Here is an example:

pxctl service node-wipe
This is a distruptive operation.
It will delete all PX configuration files from this node. Data on the storage disks attached on this node will be irrevocably deleted.
Are you sure you want to proceed ? (Y/N): y
This is a distruptive operation.
It will delete all PX configuration files from this node. Data on the storage disks attached on this node will be irrevocably deleted.
Failed to set pxd timeout. Wipe command might take more time to finish.
Are you sure you want to wipe data from the disk: ' /dev/sdb ' (Y/N): y
/dev/sdb: 8 bytes were erased at offset 0x00010040 (btrfs): 5f 42 48 52 66 53 5f 4d
Removed PX footprint from device /dev/sdb.
Wiped node successfully.

pxctl service pool

Pool maintenance

pxctl service pool
   pxctl service pool - Storage pool maintenance

   pxctl service pool command [command options] [arguments...]

   show      Show pools
   update    Update pool properties

pxctl service pool update

Updates the pool properties

pxctl service pool update --help
Update pool properties

  pxctl service pool update [flags]

      --resize               extend pool to maximum available physical storage
      --io_priority string   IO Priority (Valid Values: [high medium low]) (default "low")
      --labels string        comma separated name=value pairs (default "NoLabel")
  -h, --help                 help for update

Last edited: Friday, Jul 17, 2020